@agent-native/core 0.85.6 → 0.86.0

package/corpus/templates/design/actions/queue-fusion-edit.ts

@@ -0,0 +1,112 @@
+/**
+ * queue-fusion-edit — queue a visual edit instruction for a fusion (full-app)
+ * design.
+ *
+ * Fusion screens are iframes of a real running app, so edits cannot be
+ * applied synchronously to local HTML the way inline designs are. Instead the
+ * instruction is queued as a pending `design_fusion_edits` row; call
+ * `apply-fusion-edits` to batch pending rows into one prompt for the
+ * in-container app agent.
+ */
+
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, count, 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 { FULL_APP_BUILDING_ENABLED } from "../shared/full-app.js";
+
+const targetSchema = z.object({
+  selector: z
+    .string()
+    .optional()
+    .describe("CSS selector or data-node id of the element pointed at."),
+  path: z
+    .string()
+    .optional()
+    .describe("Route path of the screen, e.g. '/settings'."),
+  url: z.string().optional().describe("Full screen URL at edit time."),
+  nodeName: z
+    .string()
+    .optional()
+    .describe("Human-readable element description, e.g. 'primary button'."),
+});
+
+export default defineAction({
+  description:
+    "Queue a natural-language visual edit instruction for a fusion (full-app) " +
+    "design. Use this when the user requests a change to a screen backed by a " +
+    "running app container (sourceType 'fusion') — the edit cannot be applied " +
+    "synchronously like inline HTML, so it queues as a pending row. Call " +
+    "apply-fusion-edits to dispatch all pending edits to the in-container app " +
+    "agent in one batch. Pass screenFileId and/or target (selector/path/url/" +
+    "nodeName) when the user has a specific screen or element selected so the " +
+    "app agent has enough context to locate the change.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    instruction: z
+      .string()
+      .min(1)
+      .describe("Natural-language description of the requested change."),
+    screenFileId: z
+      .string()
+      .optional()
+      .describe("design_files.id of the URL-backed screen this edit targets."),
+    target: targetSchema
+      .optional()
+      .describe("Optional target context for the element/screen being edited."),
+  }),
+  run: async ({ designId, instruction, screenFileId, target }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+    const id = nanoid();
+    const now = new Date().toISOString();
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId();
+
+    await db.insert(schema.designFusionEdits).values({
+      id,
+      designId,
+      screenFileId: screenFileId ?? null,
+      instruction,
+      target: target ? JSON.stringify(target) : null,
+      status: "pending",
+      batchId: null,
+      error: null,
+      sentAt: null,
+      createdAt: now,
+      updatedAt: now,
+      ownerEmail,
+      orgId,
+    });
+
+    const [row] = await db
+      .select({ value: count() })
+      .from(schema.designFusionEdits)
+      .where(
+        and(
+          eq(schema.designFusionEdits.designId, designId),
+          eq(schema.designFusionEdits.ownerEmail, ownerEmail),
+          eq(schema.designFusionEdits.status, "pending"),
+        ),
+      );
+
+    return {
+      editId: id,
+      pendingCount: row?.value ?? 0,
+    };
+  },
+});

package/corpus/templates/design/actions/read-local-file.ts

@@ -0,0 +1,139 @@
+/**
+ * read-local-file — read one file from a connected local app via the design
+ * bridge.
+ *
+ * Security gates (in order), mirroring write-local-file.ts minus the write
+ * grant (reads do not require user write consent, only editor access + a
+ * valid bridge connection):
+ *  1. assertAccess: the caller must have editor access to the design.
+ *  2. Bridge URL resolution: only the current user's own connection row.
+ *  3. Loopback check: bridgeUrl must resolve to localhost/127.0.0.1.
+ *  4. Bridge token: the connection's stored bridge token is sent as
+ *     X-Bridge-Token so the bridge can reject unauthorized callers. The
+ *     bridge itself additionally blocks secret-looking paths (.env*, *.pem,
+ *     *.key, id_rsa*, anything under .git/) regardless of this grant.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  if (
+    normalized === "localhost" ||
+    normalized === "::1" ||
+    normalized === "[::1]"
+  ) {
+    return true;
+  }
+  const parts = normalized.split(".");
+  return (
+    parts.length === 4 &&
+    parts[0] === "127" &&
+    parts.every((part) => /^\d+$/.test(part) && Number(part) <= 255)
+  );
+}
+
+function normalizeBridgeUrl(value: string): string {
+  const parsed = new URL(value.trim());
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("bridgeUrl must be an http(s) URL");
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("bridgeUrl must not include credentials");
+  }
+  if (parsed.pathname !== "/" && parsed.pathname !== "") {
+    throw new Error("bridgeUrl must not include a path");
+  }
+  if (!isLoopbackHostname(parsed.hostname)) {
+    throw new Error("bridgeUrl must use localhost or a loopback IP address");
+  }
+  parsed.search = "";
+  parsed.hash = "";
+  parsed.pathname = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export default defineAction({
+  description:
+    "Read one file's content from a connected local app via the localhost " +
+    "design bridge. Read-only — does not require a write-consent grant, but " +
+    "does require editor access on the design and a running bridge " +
+    "connection. The bridge blocks secret-looking paths (.env*, *.pem, " +
+    "*.key, id_rsa*, anything under .git/) even for callers with editor access.",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z.string().describe("Localhost connection ID."),
+    path: z
+      .string()
+      .describe("Path to the file relative to the connection rootPath."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, connectionId, path: relPath }) => {
+    await assertAccess("design", designId, "editor");
+
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+
+    const db = getDb();
+    const [connection] = await db
+      .select({
+        bridgeUrl: schema.designLocalhostConnections.bridgeUrl,
+        bridgeToken: schema.designLocalhostConnections.bridgeToken,
+      })
+      .from(schema.designLocalhostConnections)
+      .where(
+        and(
+          eq(schema.designLocalhostConnections.id, connectionId),
+          eq(schema.designLocalhostConnections.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    if (!connection?.bridgeUrl) {
+      throw new Error(
+        `No bridge URL found for connection "${connectionId}". ` +
+          "Ensure the design bridge is running (npx @agent-native/core@latest design connect).",
+      );
+    }
+    if (!connection.bridgeToken) {
+      throw new Error(
+        `No bridge token found for connection "${connectionId}". ` +
+          "Reconnect via npx @agent-native/core@latest design connect.",
+      );
+    }
+
+    const bridgeUrl = normalizeBridgeUrl(connection.bridgeUrl);
+    const res = await fetch(`${bridgeUrl}/read-file`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Bridge-Token": connection.bridgeToken,
+      },
+      body: JSON.stringify({ relPath }),
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => res.statusText);
+      throw new Error(`Bridge read-file failed (${res.status}): ${errText}`);
+    }
+    const body = (await res.json()) as {
+      content?: string;
+      versionHash?: string;
+    };
+
+    return {
+      designId,
+      connectionId,
+      path: relPath,
+      content: body.content ?? "",
+      versionHash: body.versionHash,
+      readonly: false,
+    };
+  },
+});

package/corpus/templates/design/actions/revoke-localhost-write-consent.ts

@@ -25,24 +25,28 @@ export default defineAction({
 
     const db = getDb();
 
-    const deleted = await db
-      .delete(schema.designLocalhostWriteGrants)
-      .where(
-        and(
-          eq(schema.designLocalhostWriteGrants.designId, designId),
-          eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
-          eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
-        ),
-      );
-
-    // `deleted` shape varies by dialect; check rows affected via the object.
-    const rowsAffected =
-      (deleted as unknown as { rowsAffected?: number })?.rowsAffected ?? 0;
+    // The delete result's rows-affected shape varies by driver (and some
+    // drivers do not report it at all), so SELECT the scoped grant first and
+    // derive `revoked` from its existence — portable across dialects without
+    // assuming RETURNING support.
+    const scope = and(
+      eq(schema.designLocalhostWriteGrants.designId, designId),
+      eq(schema.designLocalhostWriteGrants.connectionId, connectionId),
+      eq(schema.designLocalhostWriteGrants.ownerEmail, ownerEmail),
+    );
+
+    const [grant] = await db
+      .select({ id: schema.designLocalhostWriteGrants.id })
+      .from(schema.designLocalhostWriteGrants)
+      .where(scope)
+      .limit(1);
+
+    await db.delete(schema.designLocalhostWriteGrants).where(scope);
 
     return {
       designId,
       connectionId,
-      revoked: rowsAffected > 0,
+      revoked: Boolean(grant),
     };
   },
 });

package/corpus/templates/design/actions/run-design-audit.ts

@@ -1,10 +1,13 @@
 /**
  * run-design-audit — read-only a11y audit over a design's rendered HTML/DOM.
  *
- * Checks contrast ratios, tap-target sizes, missing alt/labels, focus
- * visibility, and reduced-motion concerns by static analysis of the stored
- * HTML.  Does NOT perform writes.  Results are returned as `A11yFinding[]`
- * and may be persisted by the caller via `create-design-review-snapshot`.
+ * Flags low-opacity text color classes as a contrast hint (real contrast
+ * ratios require a DOM/CSS cascade resolver that isn't available server-side,
+ * so this is not a computed ratio check), plus tap-target sizes, missing
+ * alt/labels, focus visibility, and reduced-motion concerns, all by static
+ * analysis of the stored HTML. Does NOT perform writes. Results are returned
+ * as `A11yFinding[]` and may be persisted by the caller via
+ * `create-design-review-snapshot`.
  *
  * See DESIGN-STUDIO-PLAN.md §6.5 + §7 (Review surface).
  */

package/corpus/templates/design/actions/send-fusion-message.ts

@@ -0,0 +1,69 @@
+/**
+ * send-fusion-message — relay a freeform prompt to the fusion app's
+ * in-container coding agent.
+ *
+ * This is how the Design agent hands off user requests that go beyond
+ * discrete queued visual edits — e.g. "add a new page", "wire up this API",
+ * "fix this bug" — to the app's own coding agent for fusion-backed designs.
+ * Unlike queue-fusion-edit/apply-fusion-edits (which batch small visual
+ * tweaks), this sends immediately and does not persist a design_fusion_edits
+ * row.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { sendFusionBranchMessage } from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  FULL_APP_BUILDING_ENABLED,
+  readFusionApp,
+} from "../shared/full-app.js";
+
+export default defineAction({
+  description:
+    "Send a freeform natural-language prompt directly to a fusion (full-app) " +
+    "design's in-container coding agent. Use this to relay user requests that " +
+    "are broader than a single visual tweak (new features, pages, data model " +
+    "changes, bug fixes) for designs backed by a running app container. For " +
+    "small scoped visual edits on a specific screen/element, prefer " +
+    "queue-fusion-edit + apply-fusion-edits instead so edits can be batched.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    prompt: z
+      .string()
+      .min(1)
+      .describe("The message to send to the app's coding agent."),
+  }),
+  run: async ({ designId, prompt }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const access = await assertAccess("design", designId, "editor");
+    const design = access.resource as typeof schema.designs.$inferSelect;
+    const fusionApp = readFusionApp(design.data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+
+    const ownerEmail = getRequestUserEmail();
+    const result = await sendFusionBranchMessage({
+      projectId: fusionApp.projectId,
+      branchName: fusionApp.branchName,
+      prompt,
+      userEmail: ownerEmail ?? undefined,
+    });
+
+    return {
+      sent: result.sent,
+      message: result.response,
+      error: result.error,
+    };
+  },
+});

package/corpus/templates/design/actions/sync-fusion-app.ts

@@ -0,0 +1,196 @@
+/**
+ * sync-fusion-app — poll/attach the fusion branch container and refresh the
+ * design's URL-backed screens once it is ready.
+ *
+ * This is the follow-up to `create-fusion-app`: the branch container may take
+ * a while to boot, so callers poll this action until `status: "ready"`. Once
+ * ready, it upserts URL-backed screens for the given (or previously placed)
+ * paths pointing at the container's dev-server preview URL, so the canvas can
+ * render them as live iframes.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { ensureFusionContainer } from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, count, 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 {
+  DEFAULT_FUSION_SCREEN_HEIGHT,
+  DEFAULT_FUSION_SCREEN_WIDTH,
+  upsertFusionScreens,
+} from "../server/lib/fusion-screens.js";
+import {
+  FULL_APP_BUILDING_ENABLED,
+  parseDesignDataBlob,
+  readFusionApp,
+  writeFusionApp,
+} from "../shared/full-app.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+async function countPendingEdits(
+  design: Pick<typeof schema.designs.$inferSelect, "id" | "ownerEmail">,
+): Promise<number> {
+  const db = getDb();
+  const [row] = await db
+    .select({ value: count() })
+    .from(schema.designFusionEdits)
+    .where(
+      and(
+        eq(schema.designFusionEdits.designId, design.id),
+        eq(schema.designFusionEdits.ownerEmail, design.ownerEmail),
+        eq(schema.designFusionEdits.status, "pending"),
+      ),
+    );
+  return row?.value ?? 0;
+}
+
+export default defineAction({
+  description:
+    "Poll the fusion app's container status and refresh its URL-backed " +
+    "screens once ready. Call this after create-fusion-app (or periodically " +
+    "while status is 'building') to pick up the live preview URL. When ready, " +
+    "upserts screens for the given paths (or the design's existing fusion " +
+    "screens, defaulting to '/') so the canvas iframes point at the live " +
+    "container. Returns pendingEditCount so the caller knows whether queued " +
+    "edits are waiting to be applied.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    paths: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Route paths to place/refresh as screens (e.g. ['/', '/settings']). " +
+          "Defaults to the design's existing fusion screen paths, or ['/'] if none exist.",
+      ),
+  }),
+  run: async ({ designId, paths }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const access = await assertAccess("design", designId, "editor");
+    const design = access.resource as typeof schema.designs.$inferSelect;
+    const data = parseDesignDataBlob(design.data);
+    const fusionApp = readFusionApp(data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+
+    const result = await ensureFusionContainer({
+      projectId: fusionApp.projectId,
+      branchName: fusionApp.branchName,
+      timeoutMs: 20_000,
+    });
+
+    const db = getDb();
+    const now = new Date().toISOString();
+
+    if (result.status === "error") {
+      const nextData = writeFusionApp(data, {
+        ...fusionApp,
+        status: "error",
+        statusMessage: result.message ?? "Container provisioning failed",
+        updatedAt: now,
+      });
+      await db
+        .update(schema.designs)
+        .set({ data: JSON.stringify(nextData), updatedAt: now })
+        .where(eq(schema.designs.id, designId));
+      return {
+        status: "error" as const,
+        message: result.message ?? "Container provisioning failed",
+      };
+    }
+
+    if (result.status === "provisioning") {
+      const nextData = writeFusionApp(data, {
+        ...fusionApp,
+        status: "building",
+        statusMessage: result.message ?? "Container is still starting",
+        updatedAt: now,
+      });
+      await db
+        .update(schema.designs)
+        .set({ data: JSON.stringify(nextData), updatedAt: now })
+        .where(eq(schema.designs.id, designId));
+      return {
+        status: "building" as const,
+        message: result.message ?? "Container is still starting",
+      };
+    }
+
+    // ready
+    const previewUrl = result.url;
+    if (!previewUrl) {
+      throw new Error("Container reported ready but returned no preview URL");
+    }
+
+    const existingScreenMetadata = isRecord(data.screenMetadata)
+      ? (data.screenMetadata as Record<string, unknown>)
+      : {};
+    const existingFusionPaths = Object.values(existingScreenMetadata)
+      .filter(
+        (entry): entry is Record<string, unknown> =>
+          isRecord(entry) && entry.sourceType === "fusion",
+      )
+      .map((entry) => (typeof entry.path === "string" ? entry.path : undefined))
+      .filter((path): path is string => Boolean(path));
+
+    const effectivePaths =
+      paths && paths.length > 0
+        ? paths
+        : existingFusionPaths.length > 0
+          ? existingFusionPaths
+          : ["/"];
+
+    const { screens } = await upsertFusionScreens({
+      designId,
+      previewUrl,
+      paths: effectivePaths,
+      width: DEFAULT_FUSION_SCREEN_WIDTH,
+      height: DEFAULT_FUSION_SCREEN_HEIGHT,
+    });
+
+    // Re-read the design's data since upsertFusionScreens just wrote it, then
+    // layer the fusionApp update on top so we don't clobber the screen writes.
+    const [refreshed] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+    const refreshedData = parseDesignDataBlob(refreshed?.data);
+    const nextData = writeFusionApp(refreshedData, {
+      ...fusionApp,
+      previewUrl,
+      status: "ready",
+      statusMessage: result.message ?? "Container is ready",
+      updatedAt: now,
+    });
+    await db
+      .update(schema.designs)
+      .set({ data: JSON.stringify(nextData), updatedAt: now })
+      .where(eq(schema.designs.id, designId));
+
+    const pendingEditCount = await countPendingEdits(design);
+
+    return {
+      status: "ready" as const,
+      previewUrl,
+      screens: screens.map((screen) => ({
+        fileId: screen.fileId,
+        path: screen.path,
+        url: screen.url,
+        title: screen.title,
+      })),
+      pendingEditCount,
+    };
+  },
+});