@agent-native/core 0.78.8 → 0.79.0

package/corpus/templates/analytics/actions/dashboard-panel-order.ts

@@ -0,0 +1,169 @@
+export type PanelOrderTarget =
+  | { position: "top" | "bottom" }
+  | { index: number }
+  | { beforePanelId: string }
+  | { afterPanelId: string };
+
+export interface PanelOrderResult {
+  panelCount: number;
+  panelOrder: string[];
+  firstPanelIds: string[];
+  movedPanelIds: string[];
+  missingPanelIds: string[];
+  skippedDuplicatePanelIds: string[];
+  insertIndex: number;
+}
+
+function panelsFromConfig(config: Record<string, unknown>) {
+  const panels = config.panels;
+  if (!Array.isArray(panels)) {
+    throw new Error("config.panels must be an array");
+  }
+  return panels as Array<Record<string, unknown>>;
+}
+
+function panelId(panel: Record<string, unknown>): string {
+  return typeof panel.id === "string" ? panel.id : "";
+}
+
+export function getPanelOrder(config: Record<string, unknown>): string[] {
+  return panelsFromConfig(config).map(panelId).filter(Boolean);
+}
+
+export function getFirstPanelIds(
+  config: Record<string, unknown>,
+  count = 10,
+): string[] {
+  return getPanelOrder(config).slice(0, count);
+}
+
+function uniquePanelIds(ids: string[]): {
+  ids: string[];
+  duplicates: string[];
+} {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const duplicates: string[] = [];
+  for (const raw of ids) {
+    const id = raw.trim();
+    if (!id) continue;
+    if (seen.has(id)) {
+      duplicates.push(id);
+      continue;
+    }
+    seen.add(id);
+    out.push(id);
+  }
+  return { ids: out, duplicates };
+}
+
+function resolveInsertIndex(
+  remainingPanels: Array<Record<string, unknown>>,
+  target: PanelOrderTarget,
+): number {
+  if ("position" in target) {
+    return target.position === "bottom" ? remainingPanels.length : 0;
+  }
+  if ("index" in target) {
+    const index = target.index;
+    if (
+      !Number.isInteger(index) ||
+      index < 0 ||
+      index > remainingPanels.length
+    ) {
+      throw new Error(
+        `index must be an integer between 0 and ${remainingPanels.length}`,
+      );
+    }
+    return index;
+  }
+
+  const targetId =
+    "beforePanelId" in target ? target.beforePanelId : target.afterPanelId;
+  const index = remainingPanels.findIndex(
+    (panel) => panelId(panel) === targetId,
+  );
+  if (index < 0) {
+    throw new Error(`target panel "${targetId}" was not found`);
+  }
+  return "beforePanelId" in target ? index : index + 1;
+}
+
+export function movePanelsById(
+  config: Record<string, unknown>,
+  panelIds: string[],
+  target: PanelOrderTarget = { position: "top" },
+): PanelOrderResult {
+  const panels = panelsFromConfig(config);
+  const { ids, duplicates } = uniquePanelIds(panelIds);
+  if (ids.length === 0) {
+    throw new Error("panelIds must include at least one panel id");
+  }
+
+  const wanted = new Set(ids);
+  const found = new Set<string>();
+  const moving: Array<Record<string, unknown>> = [];
+  const remaining: Array<Record<string, unknown>> = [];
+
+  for (const panel of panels) {
+    const id = panelId(panel);
+    if (wanted.has(id)) {
+      found.add(id);
+      moving.push(panel);
+    } else {
+      remaining.push(panel);
+    }
+  }
+
+  const missing = ids.filter((id) => !found.has(id));
+  if (missing.length > 0) {
+    throw new Error(`panel id(s) not found: ${missing.join(", ")}`);
+  }
+
+  const orderedMoving = ids.map(
+    (id) => moving.find((panel) => panelId(panel) === id)!,
+  );
+  const insertIndex = resolveInsertIndex(remaining, target);
+  const nextPanels = [
+    ...remaining.slice(0, insertIndex),
+    ...orderedMoving,
+    ...remaining.slice(insertIndex),
+  ];
+
+  config.panels = nextPanels;
+  const order = getPanelOrder(config);
+  return {
+    panelCount: order.length,
+    panelOrder: order,
+    firstPanelIds: order.slice(0, 10),
+    movedPanelIds: ids,
+    missingPanelIds: [],
+    skippedDuplicatePanelIds: duplicates,
+    insertIndex,
+  };
+}
+
+export function applyPanelOrder(
+  config: Record<string, unknown>,
+  requestedPanelIds: string[],
+): PanelOrderResult {
+  return movePanelsById(config, requestedPanelIds, { position: "top" });
+}
+
+export function compactDashboardResult(
+  config: Record<string, unknown>,
+  movedPanelIds: string[] = [],
+): {
+  panelCount: number;
+  panelOrder: string[];
+  firstPanelIds: string[];
+  movedPanelIds: string[];
+} {
+  const order = getPanelOrder(config);
+  return {
+    panelCount: order.length,
+    panelOrder: order,
+    firstPanelIds: order.slice(0, 10),
+    movedPanelIds,
+  };
+}

package/corpus/templates/analytics/actions/get-sql-dashboard.ts

@@ -6,16 +6,83 @@ import {
 } from "@agent-native/core/server";
 import { z } from "zod";
 
+import { buildDashboardPanelGroups } from "../app/pages/adhoc/sql-dashboard/dashboard-layout";
+import {
+  clampDashboardColumns,
+  type SqlPanel,
+} from "../app/pages/adhoc/sql-dashboard/types";
 import { loadDashboardSeed } from "../server/lib/dashboard-seeds";
 import { getDashboard } from "../server/lib/dashboards-store";
+import { getPanelOrder } from "./dashboard-panel-order";
+
+function dashboardLayoutSummary(config: Record<string, unknown>) {
+  const panels = Array.isArray(config.panels)
+    ? (config.panels as SqlPanel[])
+    : [];
+  const columns = clampDashboardColumns(config.columns);
+  const groups = buildDashboardPanelGroups(panels, columns);
+  const panelOrder = getPanelOrder(config);
+
+  return {
+    panelCount: panelOrder.length,
+    panelOrder,
+    firstPanelIds: panelOrder.slice(0, 10),
+    groups: groups.map((group) => ({
+      key: group.key,
+      sectionId: group.section?.id ?? null,
+      sectionTitle: group.section?.title ?? null,
+      columns: group.columns,
+      rows: group.rows.map((row, rowIndex) => ({
+        rowIndex,
+        panelIds: row.panels.map((panel) => panel.id),
+      })),
+    })),
+  };
+}
+
+function panelSummaries(config: Record<string, unknown>) {
+  const panels = Array.isArray(config.panels)
+    ? (config.panels as Array<Record<string, unknown>>)
+    : [];
+  return panels.map((panel, index) => {
+    const panelConfig =
+      panel.config &&
+      typeof panel.config === "object" &&
+      !Array.isArray(panel.config)
+        ? (panel.config as Record<string, unknown>)
+        : {};
+    return {
+      index,
+      id: typeof panel.id === "string" ? panel.id : "",
+      title: typeof panel.title === "string" ? panel.title : "",
+      chartType: typeof panel.chartType === "string" ? panel.chartType : "",
+      source: typeof panel.source === "string" ? panel.source : undefined,
+      width: typeof panel.width === "number" ? panel.width : undefined,
+      columns: typeof panel.columns === "number" ? panel.columns : undefined,
+      tab: typeof panel.tab === "string" ? panel.tab : undefined,
+      description:
+        typeof panelConfig.description === "string"
+          ? panelConfig.description
+          : undefined,
+    };
+  });
+}
 
 function seededResponse(
   id: string,
   seed: Record<string, unknown>,
+  includeConfig: boolean,
 ): Record<string, unknown> {
-  return {
+  const base = {
     id,
-    ...seed,
+    name: typeof seed.name === "string" ? seed.name : id,
+    description:
+      typeof seed.description === "string" ? seed.description : undefined,
+    filters: seed.filters,
+    variables: seed.variables,
+    columns: seed.columns,
+    panels: panelSummaries(seed),
+    layout: dashboardLayoutSummary(seed),
     ownerEmail: null,
     orgId: null,
     visibility: "org",
@@ -23,13 +90,20 @@ function seededResponse(
     hiddenAt: null,
     hiddenBy: null,
   };
+  return includeConfig ? { ...base, ...seed } : base;
 }
 
 export default defineAction({
   description:
-    "Get a SQL analytics dashboard by ID, including its full panel config, visibility, and access metadata.",
+    "Get a SQL analytics dashboard by ID. By default this returns compact panel summaries and layout/order fields without giant SQL strings; use includeConfig=true only when you need the full dashboard config for a detailed SQL/config edit.",
   schema: z.object({
     id: z.string().describe("The dashboard ID"),
+    includeConfig: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, include the full dashboard config including panel SQL. Defaults to false to keep agent context compact.",
+      ),
   }),
   http: { method: "GET" },
   readOnly: true,
@@ -69,15 +143,23 @@ export default defineAction({
     const dash = await getDashboard(args.id, ctx);
     if (!dash || dash.kind !== "sql") {
       const seed = loadDashboardSeed(args.id);
-      if (seed) return seededResponse(args.id, seed);
+      if (seed)
+        return seededResponse(args.id, seed, args.includeConfig === true);
       throw Object.assign(new Error("Dashboard not found"), {
         statusCode: 404,
       });
     }
     const config = dash.config as Record<string, unknown>;
-    return {
+    const base = {
       id: args.id,
-      ...config,
+      name: typeof config.name === "string" ? config.name : args.id,
+      description:
+        typeof config.description === "string" ? config.description : undefined,
+      filters: config.filters,
+      variables: config.variables,
+      columns: config.columns,
+      panels: panelSummaries(config),
+      layout: dashboardLayoutSummary(config),
       ownerEmail: dash.ownerEmail,
       orgId: dash.orgId,
       visibility: dash.visibility,
@@ -90,5 +172,6 @@ export default defineAction({
       createdAt: dash.createdAt,
       updatedAt: dash.updatedAt,
     };
+    return args.includeConfig === true ? { ...base, ...config } : base;
   },
 });

package/corpus/templates/analytics/actions/mutate-dashboard.ts

@@ -0,0 +1,333 @@
+import { defineAction, embedApp } from "@agent-native/core";
+import {
+  applyText,
+  hasCollabState,
+  seedFromText,
+} from "@agent-native/core/collab";
+import {
+  buildDeepLink,
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { getDashboard, upsertDashboard } from "../server/lib/dashboards-store";
+import {
+  applyDashboardMutationOperations,
+  DASHBOARD_MUTATION_API_TYPES,
+  DASHBOARD_MUTATION_EXAMPLES,
+  parseDashboardMutationScript,
+  type DashboardMutationOperation,
+} from "./dashboard-mutation-api";
+import { compactDashboardResult } from "./dashboard-panel-order";
+import { validateDashboardConfig, validatePanelSql } from "./update-dashboard";
+
+const mutationTargetSchema = {
+  position: z.enum(["top", "bottom"]).optional(),
+  index: z.number().int().nonnegative().optional(),
+  beforePanelId: z.string().optional(),
+  afterPanelId: z.string().optional(),
+};
+
+const mutationOperationSchema = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("movePanels"),
+    panelIds: z.array(z.string()).min(1),
+    ...mutationTargetSchema,
+  }),
+  z.object({
+    op: z.literal("removePanels"),
+    panelIds: z.array(z.string()).min(1),
+  }),
+  z.object({
+    op: z.literal("updatePanel"),
+    panelId: z.string(),
+    patch: z.record(z.string(), z.unknown()),
+  }),
+  z.object({
+    op: z.literal("updatePanelPath"),
+    panelId: z.string(),
+    path: z.string(),
+    value: z.unknown(),
+  }),
+  z.object({
+    op: z.literal("insertPanel"),
+    panel: z.record(z.string(), z.unknown()),
+    ...mutationTargetSchema,
+  }),
+  z.object({
+    op: z.literal("duplicatePanel"),
+    panelId: z.string(),
+    newPanelId: z.string(),
+    patch: z.record(z.string(), z.unknown()).optional(),
+    ...mutationTargetSchema,
+  }),
+  z.object({
+    op: z.literal("setDashboard"),
+    patch: z.record(z.string(), z.unknown()),
+  }),
+]);
+
+function parseJsonArrayString(
+  value: string,
+  fieldName: string,
+): DashboardMutationOperation[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch (err: any) {
+    throw new Error(`${fieldName} must be a JSON array: ${err.message}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${fieldName} must be a JSON array`);
+  }
+  return parsed.map((op, index) => {
+    try {
+      return mutationOperationSchema.parse(op) as DashboardMutationOperation;
+    } catch (err: any) {
+      throw new Error(`${fieldName}[${index}] is invalid: ${err.message}`);
+    }
+  });
+}
+
+const operationsInputSchema = z
+  .union([
+    z.array(mutationOperationSchema),
+    z.string().transform((value) => parseJsonArrayString(value, "operations")),
+  ])
+  .optional();
+
+const apiHelp =
+  "Constrained TypeScript-like dashboard mutation script. The server parses only calls on `dashboard`; it does not execute arbitrary JavaScript. " +
+  "No variables, imports, loops, functions, templates, network, filesystem, or DB access. Arguments must be JSON-compatible literals, so quote object keys. " +
+  "Subjects: dashboard.set, dashboard.panel, dashboard.panels, dashboard.panelsMatching, dashboard.section, dashboard.insertPanel. " +
+  "Selection methods: moveToTop, moveToBottom, moveBefore, moveAfter, moveToIndex, remove, set, setTitle, setSql, setWidth, setConfig, setConfigPath, duplicate. " +
+  `Examples: ${DASHBOARD_MUTATION_EXAMPLES.slice(0, 3).join(" ")}`;
+
+function resolveScope() {
+  const orgId = getRequestOrgId() || null;
+  const email = getRequestUserEmail();
+  if (!email) throw new Error("no authenticated user");
+  return { orgId, email };
+}
+
+function resolveDashboardId(args: { dashboardId?: string; id?: string }) {
+  const dashboardId = args.dashboardId || args.id;
+  if (!dashboardId) {
+    throw new Error("provide `dashboardId` (or legacy `id`).");
+  }
+  return dashboardId;
+}
+
+function cloneConfig(config: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
+}
+
+async function syncToCollab(
+  dashboardId: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  const docId = `dash-${dashboardId}`;
+  const configStr = JSON.stringify(config);
+  try {
+    const exists = await hasCollabState(docId);
+    if (exists) {
+      await applyText(docId, configStr, "content", "agent");
+    } else {
+      await seedFromText(docId, configStr);
+    }
+  } catch {
+    // SQL remains the source of truth; live collab sync is best-effort.
+  }
+}
+
+function mutationCanChangePanelSql(op: DashboardMutationOperation): boolean {
+  if (op.op === "insertPanel" || op.op === "duplicatePanel") return true;
+  if (op.op === "setDashboard") {
+    return Object.keys(op.patch).some((key) =>
+      ["filters", "variables"].includes(key),
+    );
+  }
+  if (op.op !== "updatePanel") return false;
+  return Object.keys(op.patch).some((key) =>
+    ["sql", "source", "chartType"].includes(key),
+  );
+}
+
+function movedPanelIdsFrom(operations: DashboardMutationOperation[]): string[] {
+  const moved = new Set<string>();
+  for (const op of operations) {
+    if (op.op !== "movePanels") continue;
+    for (const id of op.panelIds) moved.add(id);
+  }
+  return Array.from(moved);
+}
+
+function helpResult() {
+  return {
+    mutationApiVersion: 1,
+    apiTypes: DASHBOARD_MUTATION_API_TYPES,
+    examples: DASHBOARD_MUTATION_EXAMPLES,
+    summary:
+      "Use `code` for constrained dashboard mutation scripts, or `operations` for the equivalent structured ops.",
+  };
+}
+
+export default defineAction({
+  description:
+    "Apply general SQL dashboard edits through a small typed mutation API in ONE atomic save. " +
+    "Prefer this for dashboard layout and panel edits: move panels by id, edit titles/SQL/width/config, remove panels, duplicate panels, insert panels, or patch dashboard fields. " +
+    "This is code-shaped but not arbitrary code execution: the server parses the allowed dashboard methods, validates the resulting config with the same invariants as update-dashboard, saves once, syncs collab, and returns compact proof. " +
+    "The main code argument is a string, so it avoids brittle JSON-pointer indexes and native-array serialization issues. " +
+    `Common example: ${DASHBOARD_MUTATION_EXAMPLES[0]}`,
+  schema: z.object({
+    dashboardId: z
+      .string()
+      .optional()
+      .describe("Dashboard id, e.g. 'agent-native-templates-first-party'."),
+    id: z
+      .string()
+      .optional()
+      .describe("Legacy alias for dashboardId. Prefer dashboardId."),
+    code: z.string().optional().describe(apiHelp),
+    operations: operationsInputSchema.describe(
+      "Structured equivalent of the typed script. Native callers should pass an array of mutation ops; shell/legacy callers may pass a JSON string. " +
+        "Supported ops: movePanels, removePanels, updatePanel, updatePanelPath, insertPanel, duplicatePanel, setDashboard.",
+    ),
+    dryRun: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, validate and return the resulting compact proof without saving.",
+      ),
+    returnConfig: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, include the full resulting dashboard config. Defaults to false to keep tool output compact.",
+      ),
+    returnTypes: z
+      .boolean()
+      .optional()
+      .describe("If true, include the allowed TypeScript API and examples."),
+  }),
+  http: { method: "POST" },
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Dashboard preview",
+      description: "Open the mutated dashboard in the real Analytics UI.",
+      iframeTitle: "Agent-Native Analytics",
+      openLabel: "Open dashboard",
+      height: 680,
+    }),
+  },
+  run: async (args) => {
+    const wantsHelpOnly =
+      args.returnTypes === true &&
+      !args.dashboardId &&
+      !args.id &&
+      !args.code &&
+      !args.operations;
+    if (wantsHelpOnly) return helpResult();
+
+    const dashboardId = resolveDashboardId(args);
+    const suppliedModes = [args.code, args.operations].filter(
+      (value) => value !== undefined,
+    ).length;
+    if (suppliedModes === 0) {
+      throw new Error("provide `code` or `operations`.");
+    }
+    if (suppliedModes > 1) {
+      throw new Error("provide only one of `code` or `operations`.");
+    }
+
+    const scope = resolveScope();
+    const ctx = { email: scope.email, orgId: scope.orgId };
+    const existing = await getDashboard(dashboardId, ctx);
+    if (!existing) {
+      throw new Error(
+        `dashboard "${dashboardId}" not found (or you don't have access).`,
+      );
+    }
+    if (existing.kind !== "sql") {
+      throw new Error(
+        `mutate-dashboard only supports SQL dashboards; "${dashboardId}" is ${existing.kind}.`,
+      );
+    }
+
+    const root = cloneConfig(existing.config as Record<string, unknown>);
+    const operations = args.operations
+      ? (args.operations as DashboardMutationOperation[])
+      : parseDashboardMutationScript(root, args.code!);
+    const mutation = applyDashboardMutationOperations(root, operations);
+
+    const validation = validateDashboardConfig(root);
+    if (validation) throw new Error(validation);
+    if (operations.some(mutationCanChangePanelSql)) {
+      const sqlError = await validatePanelSql(root);
+      if (sqlError) throw new Error(sqlError);
+    }
+
+    if (args.dryRun !== true) {
+      await upsertDashboard(dashboardId, existing.kind, root, ctx);
+      await syncToCollab(dashboardId, root);
+    }
+
+    const compact = compactDashboardResult(root, movedPanelIdsFrom(operations));
+    const summary =
+      `${args.dryRun === true ? "Dry-ran" : "Applied"} ${operations.length} dashboard mutation op(s) for "${dashboardId}". ` +
+      `First panels: ${compact.firstPanelIds.join(", ")}.`;
+
+    return {
+      id: dashboardId,
+      dashboardId,
+      name: typeof root.name === "string" ? root.name : dashboardId,
+      mutationApiVersion: 1,
+      saved: args.dryRun !== true,
+      dryRun: args.dryRun === true,
+      appliedOps: operations.length,
+      ...compact,
+      commandLog: mutation.commandLog,
+      changedPanelIds: mutation.changedPanelIds,
+      insertedPanelIds: mutation.insertedPanelIds,
+      removedPanelIds: mutation.removedPanelIds,
+      dashboardFieldsChanged: mutation.dashboardFieldsChanged,
+      ...(args.returnConfig === true ? { config: root } : {}),
+      ...(args.returnTypes === true
+        ? {
+            apiTypes: DASHBOARD_MUTATION_API_TYPES,
+            examples: DASHBOARD_MUTATION_EXAMPLES,
+          }
+        : {}),
+      summary,
+      urlPath: `/dashboards/${dashboardId}`,
+      deepLink: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId },
+      }),
+      message:
+        `${summary} ` +
+        (args.returnConfig === true
+          ? ""
+          : "Full config omitted; call get-sql-dashboard with includeConfig=true only if full SQL/config is needed."),
+    };
+  },
+  link: ({ result }) => {
+    const dashboardId =
+      result && typeof result === "object"
+        ? (result as { dashboardId?: string }).dashboardId
+        : undefined;
+    if (!dashboardId) return null;
+    return {
+      url: buildDeepLink({
+        app: "analytics",
+        view: "adhoc",
+        params: { dashboardId },
+      }),
+      label: "Open dashboard in Analytics",
+      view: "adhoc",
+    };
+  },
+});