@agent-native/core 0.85.7 → 0.86.0

package/corpus/templates/design/actions/get-fusion-deploy-status.ts

@@ -0,0 +1,86 @@
+/**
+ * get-fusion-deploy-status — read-only poll of a fusion app's last deploy.
+ *
+ * No DB writes: reads the persisted lastDeployId/deployedUrl off the fusion
+ * app linkage and asks Builder for the current deploy status.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getFusionDeploys } from "@agent-native/core/server";
+import { accessFilter } 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 {
+  FULL_APP_BUILDING_ENABLED,
+  readFusionApp,
+} from "../shared/full-app.js";
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export default defineAction({
+  description:
+    "Read-only: check the status of a fusion (full-app) design's last hosted " +
+    "deploy (queued|building|migrating|uploading|deploying|live|failed|" +
+    "canceled). Call after deploy-fusion-app to poll for completion. Makes no " +
+    "database writes.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const db = getDb();
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designs.id, designId),
+        ),
+      )
+      .limit(1);
+    if (!design) {
+      const err = new Error("Design not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+
+    const fusionApp = readFusionApp(design.data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+    if (!fusionApp.lastDeployId) {
+      throw new Error(
+        "This fusion app has not been deployed yet. Call deploy-fusion-app first.",
+      );
+    }
+
+    const deploys = await getFusionDeploys({
+      projectId: fusionApp.projectId,
+      deployId: fusionApp.lastDeployId,
+    });
+    const deploy = deploys[0];
+    const status =
+      asString(deploy?.status) ?? fusionApp.lastDeployStatus ?? "unknown";
+
+    return {
+      deployId: fusionApp.lastDeployId,
+      status,
+      url: fusionApp.deployedUrl ?? null,
+    };
+  },
+});

package/corpus/templates/design/actions/list-fusion-edits.ts

@@ -0,0 +1,96 @@
+/**
+ * list-fusion-edits — read-only list of queued fusion edit instructions for a
+ * design.
+ *
+ * Viewer access is sufficient since this is a read. Returns edits ordered
+ * oldest-first (the order apply-fusion-edits will present them to the app
+ * agent) plus a pendingCount convenience field.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, 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 { FULL_APP_BUILDING_ENABLED } from "../shared/full-app.js";
+
+function parseTarget(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export default defineAction({
+  description:
+    "List queued fusion (full-app) visual edit instructions for a design, " +
+    "oldest first. Optionally filter by status (pending|sent|error). Use to " +
+    "review what's queued before calling apply-fusion-edits, or to check the " +
+    "outcome of a previous batch.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    status: z
+      .enum(["pending", "sent", "error"])
+      .optional()
+      .describe("Filter to edits with this status. Omit to return all."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, status }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const db = getDb();
+
+    const [design] = await db
+      .select({ id: schema.designs.id })
+      .from(schema.designs)
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designs.id, designId),
+        ),
+      )
+      .limit(1);
+    if (!design) {
+      const err = new Error("Design not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+
+    const conditions = [eq(schema.designFusionEdits.designId, designId)];
+    if (status) conditions.push(eq(schema.designFusionEdits.status, status));
+
+    const rows = await db
+      .select()
+      .from(schema.designFusionEdits)
+      .where(and(...conditions))
+      .orderBy(asc(schema.designFusionEdits.createdAt));
+
+    const edits = rows.map((row) => ({
+      id: row.id,
+      instruction: row.instruction,
+      target: parseTarget(row.target),
+      status: row.status,
+      screenFileId: row.screenFileId,
+      batchId: row.batchId,
+      error: row.error,
+      sentAt: row.sentAt,
+      createdAt: row.createdAt,
+    }));
+
+    const pendingCount = rows.filter((row) => row.status === "pending").length;
+
+    return { edits, pendingCount };
+  },
+});

package/corpus/templates/design/actions/list-local-files.ts

@@ -0,0 +1,133 @@
+/**
+ * list-local-files — list files under a connected local app's root 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.
+ */
+
+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:
+    "List files under a connected local app's root 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. " +
+    "Returns root-relative paths and sizes, already filtered by the bridge's " +
+    ".gitignore-aware ignore rules, binary/size limits, and secret-path " +
+    "blocklist (.env*, *.pem, *.key, id_rsa*, .git/).",
+  schema: z.object({
+    designId: z.string().describe("Design ID."),
+    connectionId: z.string().describe("Localhost connection ID."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, connectionId }) => {
+    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}/list-files`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Bridge-Token": connection.bridgeToken,
+      },
+      body: JSON.stringify({}),
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => res.statusText);
+      throw new Error(`Bridge list-files failed (${res.status}): ${errText}`);
+    }
+    const body = (await res.json()) as {
+      files?: Array<{ path: string; size: number }>;
+      truncated?: boolean;
+    };
+
+    return {
+      designId,
+      connectionId,
+      files: body.files ?? [],
+      truncated: body.truncated ?? false,
+    };
+  },
+});

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

@@ -0,0 +1,62 @@
+/**
+ * push-fusion-app — push a fusion branch's code to its git remote.
+ *
+ * Use when the user wants the in-progress app code synced to git (e.g. before
+ * handing off to another tool, or as a checkpoint) without necessarily
+ * deploying it.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { pushFusionBranch } from "@agent-native/core/server";
+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";
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export default defineAction({
+  description:
+    "Push a fusion (full-app) design's branch code to its git remote. Use " +
+    "when the user wants the current app code synced to git as a checkpoint " +
+    "or before handing off elsewhere. Does not deploy or affect the live " +
+    "container preview — use deploy-fusion-app for a hosted deploy.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+  }),
+  run: async ({ designId }) => {
+    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 record = await pushFusionBranch({
+      projectId: fusionApp.projectId,
+      branchName: fusionApp.branchName,
+    });
+
+    const detail =
+      asString(record.message) ??
+      asString(record.commit) ??
+      asString(record.sha) ??
+      asString(record.status) ??
+      JSON.stringify(record).slice(0, 500);
+
+    return { ok: true as const, detail };
+  },
+});

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