@agent-native/core 0.80.9 → 0.80.10

package/corpus/templates/design/actions/index-components.ts

@@ -0,0 +1,258 @@
+/**
+ * index-components — read action.
+ *
+ * Scans the design's HTML for `data-agent-native-component` annotations and
+ * returns the component list plus detected instances.
+ *
+ * **Inline / Alpine tier:**  parses the design HTML directly using the
+ * code-layer projection.  Writes discovered component definitions into the
+ * `component_index` table so subsequent reads (get-component-details) can
+ * resolve persisted metadata.
+ *
+ * **Real-app tier (localhost / fusion):**  `indexComponents` capability is
+ * required.  When the source does not yet advertise it, the action returns an
+ * empty list with a `ctaRequired: true` flag and a human-readable `ctaMessage`
+ * prompting the user to Connect Builder (see DESIGN-STUDIO-PLAN.md §6.1).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { accessFilter, assertAccess } 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 {
+  detectInstances,
+  buildDefinitions,
+  type ComponentDefinition,
+  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 componentIndexId(designId: string, name: string): string {
+  // Stable deterministic id — same component name on the same design always
+  // maps to the same row so upsert is safe.
+  return `ci_${designId}_${name.toLowerCase().replace(/[^a-z0-9]/g, "_")}`;
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Scan the design's HTML for component annotations " +
+    "(`data-agent-native-component`) and return the component list plus " +
+    "detected instances. For inline/Alpine designs, parses the HTML directly " +
+    "and persists the discovered components into component_index. For real-app " +
+    "sources (localhost / fusion), the indexComponents capability must be " +
+    "available; if not, returns an empty list with ctaRequired=true and a " +
+    "message prompting the user to Connect Builder.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to index components for"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Specific design file id. Defaults to the primary index.html when omitted.",
+      ),
+  }),
+  readOnly: false,
+  http: { method: "POST" },
+  run: async ({ designId, fileId }) => {
+    const db = getDb();
+
+    // ── Access check ────────────────────────────────────────────────────────
+    // This action writes component_index rows — require editor access.
+    const access = await assertAccess("design", designId, "editor");
+
+    // ── Source type + capability check ──────────────────────────────────────
+    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 {
+        // Stale JSON — default to inline.
+      }
+    }
+
+    const sourceType = normalizeDesignSourceType(rawSourceType) ?? "inline";
+    const caps = resolveSourceCapabilities(sourceType);
+
+    // Real-app sources gate on `indexComponents`.  For inline designs this
+    // capability is `unavailable` by default (the plan marks it as a real-app
+    // feature for deep TS/cva parse) but the *annotation scan* still works
+    // from the DOM — we always run it.  The flag tells callers whether the
+    // full real-app index is live or whether they see only annotations.
+    const hasFullIndex = hasCapability(caps, "indexComponents");
+    const ctaRequired =
+      sourceType !== "inline" && !hasCapability(caps, "indexComponents");
+
+    if (ctaRequired) {
+      return {
+        designId,
+        sourceType,
+        ctaRequired: true,
+        ctaMessage:
+          "Full component indexing (prop types, cva variants, Storybook " +
+          "stories, jump-to-source) requires a connected Builder app. " +
+          "Connect Builder via the Make it real CTA to unlock this feature.",
+        components: [] as ComponentDefinition[],
+        instances: [] as ComponentInstance[],
+        totalComponents: 0,
+        totalInstances: 0,
+      };
+    }
+
+    // ── Fetch the 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 + detection ───────────────────────────────────────────────
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const instances = detectInstances(projection.nodes);
+    const definitions = buildDefinitions(instances);
+
+    // ── Persist discovered components ────────────────────────────────────────
+    // Write each distinct component name into component_index so that
+    // get-component-details can resolve metadata by node id.
+    const now = new Date().toISOString();
+    // Derive the owner from the request user, falling back to the design's
+    // owner. Never stamp an empty-string owner (an unowned row): require a real
+    // owner before writing a new component_index row.
+    const designOwner = (access.resource as { ownerEmail?: unknown })
+      .ownerEmail;
+    const ownerEmail =
+      getRequestUserEmail() ??
+      (typeof designOwner === "string" && designOwner ? designOwner : null);
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    for (const def of definitions) {
+      const id = componentIndexId(designId, def.name);
+      const existing = await db
+        .select({ id: schema.componentIndex.id })
+        .from(schema.componentIndex)
+        .where(eq(schema.componentIndex.id, id))
+        .limit(1);
+
+      if (existing.length === 0) {
+        await db.insert(schema.componentIndex).values({
+          id,
+          designId,
+          name: def.name,
+          runtimeSelectors: JSON.stringify(
+            def.instanceNodeIds.map(
+              (nodeId) => `[data-agent-native-node-id="${nodeId}"]`,
+            ),
+          ),
+          ownerEmail,
+          createdAt: now,
+          updatedAt: now,
+        });
+      } else {
+        await db
+          .update(schema.componentIndex)
+          .set({
+            runtimeSelectors: JSON.stringify(
+              def.instanceNodeIds.map(
+                (nodeId) => `[data-agent-native-node-id="${nodeId}"]`,
+              ),
+            ),
+            updatedAt: now,
+          })
+          .where(eq(schema.componentIndex.id, id));
+      }
+    }
+
+    // Annotate instances with their component_index id.
+    const indexMap = new Map(
+      definitions.map((def) => [
+        def.name,
+        componentIndexId(designId, def.name),
+      ]),
+    );
+    const annotatedInstances = instances.map((inst) => ({
+      ...inst,
+      componentIndexId: indexMap.get(inst.name),
+    }));
+
+    return {
+      designId,
+      sourceType,
+      ctaRequired: false,
+      hasFullIndex,
+      components: definitions,
+      instances: annotatedInstances,
+      totalComponents: definitions.length,
+      totalInstances: instances.length,
+      note:
+        sourceType === "inline"
+          ? "Showing annotated Alpine components from data-agent-native-component attributes. Connect Builder for full TS prop types and cva variants."
+          : undefined,
+    };
+  },
+});

package/corpus/templates/design/actions/index-design-tokens.ts

@@ -0,0 +1,273 @@
+import { defineAction } from "@agent-native/core";
+import { extractCssVars } from "@agent-native/core/server/design-token-utils";
+import { 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 type { DesignSystemData } from "../shared/api.js";
+import { resolveTweaksToCssVars } from "../shared/resolve-tweaks.js";
+
+// ---------------------------------------------------------------------------
+// Token type classification
+// ---------------------------------------------------------------------------
+
+function classifyVar(
+  name: string,
+  value: string,
+): "color" | "typography" | "spacing" | "radius" | "shadow" | "other" {
+  const n = name.toLowerCase();
+  if (
+    /color|bg|background|text|border|accent|primary|secondary|surface|muted|foreground|fill|stroke/i.test(
+      n,
+    ) ||
+    /^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\(|oklch\(|color\()/.test(value.trim())
+  ) {
+    return "color";
+  }
+  if (/font|size|leading|tracking|weight|heading|body|type/i.test(n)) {
+    return "typography";
+  }
+  if (/radius|rounded/i.test(n)) {
+    return "radius";
+  }
+  if (/spacing|gap|padding|margin|space/i.test(n)) {
+    return "spacing";
+  }
+  if (/shadow|blur|drop/i.test(n)) {
+    return "shadow";
+  }
+  return "other";
+}
+
+/** Derive a friendly display name from a CSS var name like `--primary-color`. */
+function friendlyName(cssVar: string): string {
+  return cssVar
+    .replace(/^--/, "")
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// ---------------------------------------------------------------------------
+// Token entry shape
+// ---------------------------------------------------------------------------
+
+export interface DesignToken {
+  /** Human-readable display name, e.g. "Primary Color". */
+  name: string;
+  /** CSS custom property, e.g. "--primary-color". */
+  cssVar: string;
+  /** Resolved string value, e.g. "#3B82F6" or "0.5rem". */
+  value: string;
+  /** Semantic token category. */
+  type: "color" | "typography" | "spacing" | "radius" | "shadow" | "other";
+  /** Opaque source chip label, e.g. "globals.css" or "Brand Kit". */
+  source: string;
+  /**
+   * True when the value comes from the design's own tweak selections (i.e.
+   * the user has already customised this token in the editor).
+   */
+  isTweakOverride?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Action
+// ---------------------------------------------------------------------------
+
+export default defineAction({
+  description:
+    "Index the design tokens for a design as a friendly { name, cssVar, " +
+    "value, type, source } list. Parses CSS custom properties from the " +
+    "design's HTML :root block, the linked Brand Kit / design system, and " +
+    "the user's applied tweak selections.  Returns tokens grouped by type " +
+    "(color, typography, spacing, radius, shadow, other).",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    const access = await resolveAccess("design", designId);
+    if (!access) {
+      throw new Error("Design not found");
+    }
+    const design = access.resource;
+    const db = getDb();
+
+    // ------------------------------------------------------------------
+    // 1. Parse tokens from the design's own HTML files (:root vars)
+    // ------------------------------------------------------------------
+    const files = await db
+      .select({
+        filename: schema.designFiles.filename,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .where(eq(schema.designFiles.designId, designId));
+
+    /** cssVar -> { value, source } */
+    const rawTokens: Map<string, { value: string; source: string }> = new Map();
+
+    for (const file of files) {
+      const state = {
+        colors: {} as Record<string, string>,
+        cssCustomProperties: {} as Record<string, string>,
+        fonts: [],
+        spacing: {} as Record<string, string>,
+        borderRadius: {} as Record<string, string>,
+        stylingFramework: null,
+        rawExtracts: [],
+        seenFonts: new Set<string>(),
+      };
+      extractCssVars(state, file.content);
+      for (const [k, v] of Object.entries(state.cssCustomProperties)) {
+        rawTokens.set(k, { value: v, source: file.filename });
+      }
+    }
+
+    // ------------------------------------------------------------------
+    // 2. Overlay tokens from the linked Brand Kit / design system
+    // ------------------------------------------------------------------
+    if (design.designSystemId) {
+      // Design systems are their own access boundary (same pattern as
+      // get-design-system.ts). A user who can read the design but has no
+      // access to the linked design system must NOT receive its tokens.
+      const dsAccess = await resolveAccess(
+        "design-system",
+        design.designSystemId,
+      );
+
+      const [dsRow] = dsAccess
+        ? await db
+            .select({ data: schema.designSystems.data })
+            .from(schema.designSystems)
+            .where(eq(schema.designSystems.id, design.designSystemId))
+            .limit(1)
+        : [];
+
+      if (dsRow?.data) {
+        try {
+          const dsData = JSON.parse(dsRow.data) as Partial<DesignSystemData>;
+          // Flatten the Brand Kit's known token fields into CSS vars
+          const brandColors = dsData.colors ?? {};
+          const colorRoleMap: Record<string, string> = {
+            primary: "--color-primary",
+            secondary: "--color-secondary",
+            accent: "--color-accent",
+            background: "--color-background",
+            surface: "--color-surface",
+            text: "--color-text",
+            textMuted: "--color-text-muted",
+          };
+          for (const [role, cssVar] of Object.entries(colorRoleMap)) {
+            const v = (brandColors as Record<string, string>)[role];
+            if (v) rawTokens.set(cssVar, { value: v, source: "Brand Kit" });
+          }
+          // Border radius
+          if (dsData.borders?.radius) {
+            rawTokens.set("--radius", {
+              value: dsData.borders.radius,
+              source: "Brand Kit",
+            });
+          }
+          // Spacing
+          if (dsData.spacing?.elementGap) {
+            rawTokens.set("--spacing-element-gap", {
+              value: dsData.spacing.elementGap,
+              source: "Brand Kit",
+            });
+          }
+          if (dsData.spacing?.pagePadding) {
+            rawTokens.set("--spacing-page-padding", {
+              value: dsData.spacing.pagePadding,
+              source: "Brand Kit",
+            });
+          }
+        } catch {
+          // Malformed JSON — skip Brand Kit overlay silently.
+        }
+      }
+    }
+
+    // ------------------------------------------------------------------
+    // 3. Overlay tweak-resolved values (user customisations win)
+    // ------------------------------------------------------------------
+    let designData: Record<string, unknown> = {};
+    try {
+      designData = design.data
+        ? (JSON.parse(design.data) as Record<string, unknown>)
+        : {};
+    } catch {
+      // ignore
+    }
+    const tweaks = Array.isArray(designData.tweaks)
+      ? (designData.tweaks as Array<{
+          id: string;
+          cssVar?: string;
+          defaultValue: unknown;
+        }>)
+      : [];
+    const tweakSelections =
+      designData.tweakSelections &&
+      typeof designData.tweakSelections === "object" &&
+      !Array.isArray(designData.tweakSelections)
+        ? (designData.tweakSelections as Record<
+            string,
+            string | number | boolean
+          >)
+        : {};
+
+    // Cast tweaks array to the shape resolveTweaksToCssVars expects
+    type TweakDef = Parameters<typeof resolveTweaksToCssVars>[0][number];
+    const resolvedOverrides = resolveTweaksToCssVars(
+      tweaks as TweakDef[],
+      tweakSelections,
+    );
+    const tweakCssVars = new Set(
+      tweaks.map((t) => t.cssVar).filter(Boolean) as string[],
+    );
+    for (const [cssVar, value] of Object.entries(resolvedOverrides)) {
+      rawTokens.set(cssVar, { value, source: "Tweaks" });
+    }
+
+    // ------------------------------------------------------------------
+    // 4. Build friendly token list
+    // ------------------------------------------------------------------
+    const tokens: DesignToken[] = [];
+    for (const [cssVar, { value, source }] of rawTokens) {
+      tokens.push({
+        name: friendlyName(cssVar),
+        cssVar,
+        value,
+        type: classifyVar(cssVar, value),
+        source,
+        isTweakOverride: tweakCssVars.has(cssVar),
+      });
+    }
+
+    // Group by type for the panel
+    type TokenGroup = { type: DesignToken["type"]; tokens: DesignToken[] };
+    const ORDER: DesignToken["type"][] = [
+      "color",
+      "typography",
+      "spacing",
+      "radius",
+      "shadow",
+      "other",
+    ];
+    const byType = new Map<DesignToken["type"], DesignToken[]>(
+      ORDER.map((t) => [t, []]),
+    );
+    for (const tok of tokens) {
+      byType.get(tok.type)!.push(tok);
+    }
+    const groups: TokenGroup[] = [];
+    for (const type of ORDER) {
+      const toks = byType.get(type)!;
+      if (toks.length > 0) groups.push({ type, tokens: toks });
+    }
+
+    return { designId, tokenCount: tokens.length, groups, tokens };
+  },
+});