@agent-native/core 0.96.0 → 0.98.0

package/corpus/templates/analytics/server/lib/dashboards-store.ts

@@ -1,3 +1,18 @@
+/**
+ * Dashboards + analyses store — SQL first, legacy settings-KV as
+ * read-only fallback. Writes always go to SQL.
+ *
+ * Lazy migration: when a record is fetched by id and exists only in the
+ * legacy settings store, it is copied into SQL on the fly using the
+ * settings key as the source of truth for `ownerEmail` / `orgId` /
+ * `visibility`, then returned. Subsequent reads hit SQL directly.
+ *
+ * - `u:<email>:dashboard-{id}`     → kind='explorer', owner=email,  visibility='private'
+ * - `u:<email>:sql-dashboard-{id}` → kind='sql',      owner=email,  visibility='private'
+ * - `o:<orgId>:sql-dashboard-{id}` → kind='sql',      owner=caller, visibility='org'
+ * - `adhoc-analysis-{id}`          → owner=caller,   legacy visibility from its source key
+ */
+import { isPostgres } from "@agent-native/core/db";
 import { recordChange } from "@agent-native/core/server";
 import {
   getAllSettings,
@@ -13,21 +28,7 @@ import {
   resolveAccess,
   type ShareRole,
 } from "@agent-native/core/sharing";
-/**
- * Dashboards + analyses store — SQL first, legacy settings-KV as
- * read-only fallback. Writes always go to SQL.
- *
- * Lazy migration: when a record is fetched by id and exists only in the
- * legacy settings store, it is copied into SQL on the fly using the
- * settings key as the source of truth for `ownerEmail` / `orgId` /
- * `visibility`, then returned. Subsequent reads hit SQL directly.
- *
- * - `u:<email>:dashboard-{id}`     → kind='explorer', owner=email,  visibility='private'
- * - `u:<email>:sql-dashboard-{id}` → kind='sql',      owner=email,  visibility='private'
- * - `o:<orgId>:sql-dashboard-{id}` → kind='sql',      owner=caller, visibility='org'
- * - `adhoc-analysis-{id}`          → owner=caller,   legacy visibility from its source key
- */
-import { and, desc, eq, isNotNull, isNull } from "drizzle-orm";
+import { and, desc, eq, isNotNull, isNull, sql } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
 
@@ -56,6 +57,22 @@ export interface DashboardRecord {
   canManage?: boolean;
 }
 
+/** Metadata-only dashboard row for navigation and picker surfaces. */
+export interface DashboardSummaryRecord {
+  id: string;
+  kind: DashboardKind;
+  name: string;
+  parentId: string | null;
+  ownerEmail: string;
+  orgId: string | null;
+  visibility: "private" | "org" | "public";
+  createdAt: string;
+  updatedAt: string;
+  archivedAt: string | null;
+  hiddenAt: string | null;
+  hiddenBy: string | null;
+}
+
 export interface DashboardRevisionRecord {
   id: string;
   dashboardId: string;
@@ -129,6 +146,58 @@ function nanoidFallback(): string {
   );
 }
 
+/**
+ * Normalize affected-row metadata from every createGetDb backend: libSQL,
+ * PGlite, Neon, postgres.js, better-sqlite3, and D1. Mirrors
+ * templates/design/actions/update-design.ts's `affectedRowCount`.
+ */
+function affectedRowCount(result: unknown): number | undefined {
+  const candidate = result as
+    | {
+        rowsAffected?: unknown;
+        affectedRows?: unknown;
+        rowCount?: unknown;
+        count?: unknown;
+        changes?: unknown;
+        meta?: { changes?: unknown };
+      }
+    | undefined;
+  const value =
+    candidate?.rowsAffected ??
+    candidate?.affectedRows ??
+    candidate?.rowCount ??
+    candidate?.count ??
+    candidate?.changes ??
+    candidate?.meta?.changes;
+  return typeof value === "number" ? value : undefined;
+}
+
+/**
+ * Thrown when a fenced `upsertDashboard` write (an `expectedUpdatedAt` was
+ * supplied) loses its compare-and-swap because another writer changed the
+ * row first. Callers should re-read the dashboard and re-apply their mutation
+ * against the fresh config — see `upsertDashboardWithRetry`.
+ */
+export class DashboardConflictError extends Error {
+  constructor(id: string) {
+    super(`Dashboard "${id}" changed between read and write.`);
+    this.name = "DashboardConflictError";
+  }
+}
+
+/**
+ * Thrown when a fenced `upsertAnalysis` write (an `expectedUpdatedAt` was
+ * supplied) loses its compare-and-swap because another writer changed the
+ * row first. Callers should re-read the analysis and re-apply their mutation
+ * against the fresh record — see `upsertAnalysisWithRetry`.
+ */
+export class AnalysisConflictError extends Error {
+  constructor(id: string) {
+    super(`Analysis "${id}" changed between read and write.`);
+    this.name = "AnalysisConflictError";
+  }
+}
+
 function changeScope(
   ownerEmail: string,
   orgId: string | null,
@@ -426,6 +495,125 @@ export async function listDashboards(
   return out;
 }
 
+/**
+ * List dashboard metadata without transferring or parsing each dashboard's
+ * potentially very large panel config. This is the list-path counterpart to
+ * `getDashboard`, which remains the full-config detail read.
+ *
+ * Legacy settings rows are surfaced directly instead of being migrated during
+ * the read. Opening one by id still performs the existing lazy migration, but
+ * navigation no longer turns an ordinary list into N sequential writes.
+ */
+export async function listDashboardSummaries(
+  ctx: AccessCtx,
+  filter?: {
+    kind?: DashboardKind;
+    archived?: DashboardArchiveFilter;
+    hidden?: DashboardHiddenFilter;
+  },
+): Promise<DashboardSummaryRecord[]> {
+  const db = getDb() as any;
+  const archived = filter?.archived ?? "active";
+  const hidden = filter?.hidden ?? "visible";
+  const conditions: any[] = [
+    accessFilter(schema.dashboards, schema.dashboardShares, {
+      userEmail: ctx.email,
+      orgId: ctx.orgId ?? undefined,
+    }),
+  ];
+  if (filter?.kind) conditions.push(eq(schema.dashboards.kind, filter.kind));
+  if (archived === "active")
+    conditions.push(isNull(schema.dashboards.archivedAt));
+  else if (archived === "archived")
+    conditions.push(isNotNull(schema.dashboards.archivedAt));
+  if (hidden === "visible") conditions.push(isNull(schema.dashboards.hiddenAt));
+  else if (hidden === "hidden")
+    conditions.push(isNotNull(schema.dashboards.hiddenAt));
+  const where = conditions.length === 1 ? conditions[0] : and(...conditions);
+  const parentId = isPostgres()
+    ? sql<string | null>`(${schema.dashboards.config}::jsonb ->> 'parentId')`
+    : sql<
+        string | null
+      >`json_extract(${schema.dashboards.config}, '$.parentId')`;
+  const rows = await db
+    .select({
+      id: schema.dashboards.id,
+      kind: schema.dashboards.kind,
+      name: schema.dashboards.title,
+      parentId,
+      ownerEmail: schema.dashboards.ownerEmail,
+      orgId: schema.dashboards.orgId,
+      visibility: schema.dashboards.visibility,
+      createdAt: schema.dashboards.createdAt,
+      updatedAt: schema.dashboards.updatedAt,
+      archivedAt: schema.dashboards.archivedAt,
+      hiddenAt: schema.dashboards.hiddenAt,
+      hiddenBy: schema.dashboards.hiddenBy,
+    })
+    .from(schema.dashboards)
+    .where(where);
+  const out: DashboardSummaryRecord[] = rows.map((row: any) => ({
+    ...row,
+    parentId: typeof row.parentId === "string" ? row.parentId : null,
+    orgId: row.orgId ?? null,
+    archivedAt: row.archivedAt ?? null,
+    hiddenAt: row.hiddenAt ?? null,
+    hiddenBy: row.hiddenBy ?? null,
+  }));
+  const seen = new Set(out.map((row) => row.id));
+
+  if (archived === "archived" || hidden === "hidden") return out;
+  try {
+    const all = await getAllSettings();
+    for (const [key, value] of Object.entries(all)) {
+      let id: string | null = null;
+      let kind: DashboardKind | null = null;
+      let orgId: string | null = null;
+      let visibility: DashboardSummaryRecord["visibility"] = "private";
+      if (ctx.orgId && key.startsWith(`o:${ctx.orgId}:${SQL_PREFIX}`)) {
+        id = key.slice(`o:${ctx.orgId}:${SQL_PREFIX}`.length);
+        kind = "sql";
+        orgId = ctx.orgId;
+        visibility = "org";
+      } else if (ctx.email && key.startsWith(`u:${ctx.email}:${SQL_PREFIX}`)) {
+        id = key.slice(`u:${ctx.email}:${SQL_PREFIX}`.length);
+        kind = "sql";
+      } else if (
+        ctx.email &&
+        key.startsWith(`u:${ctx.email}:${EXPLORER_PREFIX}`)
+      ) {
+        id = key.slice(`u:${ctx.email}:${EXPLORER_PREFIX}`.length);
+        kind = "explorer";
+      }
+      if (!id || !kind || seen.has(id)) continue;
+      if (filter?.kind && filter.kind !== kind) continue;
+      seen.add(id);
+      const config = value as Record<string, unknown>;
+      const { title } = configFromSettings(config);
+      const createdAt =
+        typeof config.createdAt === "string" ? config.createdAt : nowIso();
+      out.push({
+        id,
+        kind,
+        name: title,
+        parentId: typeof config.parentId === "string" ? config.parentId : null,
+        ownerEmail: ctx.email,
+        orgId,
+        visibility,
+        createdAt,
+        updatedAt:
+          typeof config.updatedAt === "string" ? config.updatedAt : createdAt,
+        archivedAt: null,
+        hiddenAt: null,
+        hiddenBy: null,
+      });
+    }
+  } catch {
+    // Legacy scan is best-effort.
+  }
+  return out;
+}
+
 async function pruneDashboardRevisions(
   db: any,
   dashboardId: string,
@@ -466,15 +654,33 @@ async function snapshotDashboardRevision(
  * Upsert a dashboard. On create, caller becomes owner and visibility defaults
  * to `private`; users explicitly promote useful dashboards to org/public via
  * sharing. On update, `assertAccess` requires `editor`.
+ *
+ * `expectedUpdatedAt` fences the update against concurrent writers: pass the
+ * `updatedAt` observed by an earlier `getDashboard` call and the UPDATE only
+ * applies `WHERE id = ? AND updated_at = ?`. If another writer already saved
+ * in between, the fenced UPDATE affects zero rows and this throws
+ * `DashboardConflictError` instead of silently clobbering their write. Omit
+ * it (the default) to keep the prior unconditional last-write-wins behavior,
+ * which existing callers (legacy migration, revision restore, and any
+ * one-shot write that isn't a read-modify-write) still rely on.
  */
 export async function upsertDashboard(
   id: string,
   kind: DashboardKind,
   body: Record<string, unknown>,
   ctx: AccessCtx,
+  expectedUpdatedAt?: string,
 ): Promise<DashboardRecord> {
   // If the row exists (or legacy-migrates), require editor.
   const existing = await getDashboard(id, ctx);
+  if (!existing && expectedUpdatedAt !== undefined) {
+    // A fence was supplied against a specific prior version, but the row is
+    // gone (deleted, or a legacy key that failed to migrate) by the time we
+    // looked. Treat this as a conflict rather than silently creating a fresh
+    // row — the caller's mutation was computed against state that no longer
+    // exists.
+    throw new DashboardConflictError(id);
+  }
   const db = getDb() as any;
   const { title, config } = configFromSettings(body);
   const configJson = JSON.stringify(config);
@@ -487,17 +693,43 @@ export async function upsertDashboard(
       existing.kind !== kind ||
       existing.title !== title ||
       JSON.stringify(existing.config) !== configJson;
-    if (changed) await snapshotDashboardRevision(db, existing, ctx);
-    await db
-      .update(schema.dashboards)
-      .set({
-        kind,
-        title,
-        config: configJson,
-        updatedAt: nowIso(),
-        updatedBy: ctx.email,
-      })
-      .where(eq(schema.dashboards.id, id));
+    const setValues = {
+      kind,
+      title,
+      config: configJson,
+      updatedAt: nowIso(),
+      updatedBy: ctx.email,
+    };
+    if (expectedUpdatedAt !== undefined) {
+      // Fenced write. Snapshot the revision only after we know this exact
+      // write actually landed — otherwise a lost race would record a
+      // revision for a save that never happened.
+      const updateResult = await db
+        .update(schema.dashboards)
+        .set(setValues)
+        .where(
+          and(
+            eq(schema.dashboards.id, id),
+            eq(schema.dashboards.updatedAt, expectedUpdatedAt),
+          ),
+        );
+      const affected = affectedRowCount(updateResult);
+      if (affected === undefined) {
+        throw new Error(
+          "The database driver did not report an affected-row count for the fenced dashboard update.",
+        );
+      }
+      if (affected === 0) {
+        throw new DashboardConflictError(id);
+      }
+      if (changed) await snapshotDashboardRevision(db, existing, ctx);
+    } else {
+      if (changed) await snapshotDashboardRevision(db, existing, ctx);
+      await db
+        .update(schema.dashboards)
+        .set(setValues)
+        .where(eq(schema.dashboards.id, id));
+    }
   } else {
     await db.insert(schema.dashboards).values({
       id,
@@ -528,6 +760,66 @@ export async function upsertDashboard(
   return dashboard;
 }
 
+/** Max attempts (first try + retries) for `upsertDashboardWithRetry`. */
+export const DASHBOARD_SAVE_MAX_ATTEMPTS = 3;
+
+/**
+ * Read-modify-write helper for the four action call sites that fetch a
+ * dashboard, mutate its config in memory, then save it back. Fences every
+ * save with the `updatedAt` of the record `mutate` was given, so a
+ * concurrent writer (agent adds a panel while a human drags one, or two
+ * agent calls race) never gets silently clobbered.
+ *
+ * `mutate` is invoked with the freshest `DashboardRecord` on every attempt —
+ * re-fetched from `getDashboard` each time — and must recompute the
+ * `{ kind, body }` to save FROM THAT RECORD, not from a closure over an
+ * earlier read; only then does a retry actually merge both writers' changes
+ * instead of re-deriving the same stale result. `mutate` may throw a
+ * non-conflict error (e.g. validation) to abort immediately without
+ * retrying.
+ *
+ * On a lost race, this re-reads and re-invokes `mutate` up to `maxAttempts`
+ * times before failing loud with a clear error so callers never silently
+ * drop a write or loop forever.
+ */
+export async function upsertDashboardWithRetry(
+  id: string,
+  ctx: AccessCtx,
+  mutate: (
+    existing: DashboardRecord,
+  ) =>
+    | { kind: DashboardKind; body: Record<string, unknown> }
+    | Promise<{ kind: DashboardKind; body: Record<string, unknown> }>,
+  maxAttempts: number = DASHBOARD_SAVE_MAX_ATTEMPTS,
+): Promise<DashboardRecord> {
+  let lastConflict: unknown;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const existing = await getDashboard(id, ctx);
+    if (!existing) {
+      throw new Error(
+        `dashboard "${id}" not found (or you don't have access).`,
+      );
+    }
+    const { kind, body } = await mutate(existing);
+    try {
+      return await upsertDashboard(id, kind, body, ctx, existing.updatedAt);
+    } catch (err) {
+      if (err instanceof DashboardConflictError) {
+        lastConflict = err;
+        continue;
+      }
+      throw err;
+    }
+  }
+  const finalError = new Error(
+    `Could not save dashboard "${id}" after ${maxAttempts} attempt(s); it kept changing concurrently. Re-read the dashboard and try again.`,
+  );
+  if (lastConflict !== undefined) {
+    (finalError as Error & { cause?: unknown }).cause = lastConflict;
+  }
+  throw finalError;
+}
+
 export async function listDashboardRevisions(
   dashboardId: string,
   ctx: AccessCtx,
@@ -1104,6 +1396,21 @@ async function snapshotAnalysisRevision(
   await pruneAnalysisRevisions(db, analysis.id);
 }
 
+/**
+ * Upsert an analysis. On create, caller becomes owner and visibility defaults
+ * to `private`. On update, `assertAccess` requires `editor`.
+ *
+ * `expectedUpdatedAt` fences the update against concurrent writers: pass the
+ * `updatedAt` observed by an earlier `getAnalysis` call and the UPDATE only
+ * applies `WHERE id = ? AND updated_at = ?`. If another writer already saved
+ * in between, the fenced UPDATE affects zero rows and this throws
+ * `AnalysisConflictError` instead of silently clobbering their write. Omit it
+ * (the default) to keep the prior unconditional last-write-wins behavior,
+ * which existing callers (legacy migration, revision restore, and
+ * `save-analysis`'s create/re-run path) still rely on. See
+ * `upsertAnalysisWithRetry` for the read-modify-write pattern that recomputes
+ * the patch from fresh state on a lost race.
+ */
 export async function upsertAnalysis(
   id: string,
   body: {
@@ -1116,8 +1423,17 @@ export async function upsertAnalysis(
     resultData?: Record<string, unknown> | null;
   },
   ctx: AccessCtx,
+  expectedUpdatedAt?: string,
 ): Promise<AnalysisRecord> {
   const existing = await getAnalysis(id, ctx);
+  if (!existing && expectedUpdatedAt !== undefined) {
+    // A fence was supplied against a specific prior version, but the row is
+    // gone (deleted, or a legacy key that failed to migrate) by the time we
+    // looked. Treat this as a conflict rather than silently creating a fresh
+    // row — the caller's mutation was computed against state that no longer
+    // exists.
+    throw new AnalysisConflictError(id);
+  }
   const db = getDb() as any;
   if (existing) {
     await assertAccess("analysis", id, "editor", {
@@ -1162,11 +1478,36 @@ export async function upsertAnalysis(
         JSON.stringify(existing.dataSources) ||
       next.resultMarkdown !== existing.resultMarkdown ||
       JSON.stringify(next.resultData) !== JSON.stringify(existing.resultData);
-    if (changed) await snapshotAnalysisRevision(db, existing, ctx);
-    await db
-      .update(schema.analyses)
-      .set(patch)
-      .where(eq(schema.analyses.id, id));
+    if (expectedUpdatedAt !== undefined) {
+      // Fenced write. Snapshot the revision only after we know this exact
+      // write actually landed — otherwise a lost race would record a
+      // revision for a save that never happened.
+      const updateResult = await db
+        .update(schema.analyses)
+        .set(patch)
+        .where(
+          and(
+            eq(schema.analyses.id, id),
+            eq(schema.analyses.updatedAt, expectedUpdatedAt),
+          ),
+        );
+      const affected = affectedRowCount(updateResult);
+      if (affected === undefined) {
+        throw new Error(
+          "The database driver did not report an affected-row count for the fenced analysis update.",
+        );
+      }
+      if (affected === 0) {
+        throw new AnalysisConflictError(id);
+      }
+      if (changed) await snapshotAnalysisRevision(db, existing, ctx);
+    } else {
+      if (changed) await snapshotAnalysisRevision(db, existing, ctx);
+      await db
+        .update(schema.analyses)
+        .set(patch)
+        .where(eq(schema.analyses.id, id));
+    }
   } else {
     await db.insert(schema.analyses).values({
       id,
@@ -1194,6 +1535,77 @@ export async function upsertAnalysis(
   return rowToAnalysis(row);
 }
 
+/** Max attempts (first try + retries) for `upsertAnalysisWithRetry`. */
+export const ANALYSIS_SAVE_MAX_ATTEMPTS = 3;
+
+/**
+ * Read-modify-write helper for action call sites that fetch an analysis,
+ * mutate its fields in memory, then save it back. Fences every save with the
+ * `updatedAt` of the record `mutate` was given, so a concurrent writer (e.g.
+ * `save-analysis` re-running with fresh results while someone renames it)
+ * never gets silently clobbered.
+ *
+ * `mutate` is invoked with the freshest `AnalysisRecord` on every attempt —
+ * re-fetched from `getAnalysis` each time — and must recompute the body patch
+ * to save FROM THAT RECORD, not from a closure over an earlier read; only
+ * then does a retry actually merge both writers' changes instead of
+ * re-deriving the same stale result. `mutate` may throw a non-conflict error
+ * (e.g. validation) to abort immediately without retrying.
+ *
+ * On a lost race, this re-reads and re-invokes `mutate` up to `maxAttempts`
+ * times before failing loud with a clear error so callers never silently
+ * drop a write or loop forever.
+ */
+export async function upsertAnalysisWithRetry(
+  id: string,
+  ctx: AccessCtx,
+  mutate: (existing: AnalysisRecord) =>
+    | {
+        name?: string;
+        description?: string;
+        question?: string;
+        instructions?: string;
+        dataSources?: string[];
+        resultMarkdown?: string;
+        resultData?: Record<string, unknown> | null;
+      }
+    | Promise<{
+        name?: string;
+        description?: string;
+        question?: string;
+        instructions?: string;
+        dataSources?: string[];
+        resultMarkdown?: string;
+        resultData?: Record<string, unknown> | null;
+      }>,
+  maxAttempts: number = ANALYSIS_SAVE_MAX_ATTEMPTS,
+): Promise<AnalysisRecord> {
+  let lastConflict: unknown;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const existing = await getAnalysis(id, ctx);
+    if (!existing) {
+      throw new Error(`analysis "${id}" not found (or you don't have access).`);
+    }
+    const body = await mutate(existing);
+    try {
+      return await upsertAnalysis(id, body, ctx, existing.updatedAt);
+    } catch (err) {
+      if (err instanceof AnalysisConflictError) {
+        lastConflict = err;
+        continue;
+      }
+      throw err;
+    }
+  }
+  const finalError = new Error(
+    `Could not save analysis "${id}" after ${maxAttempts} attempt(s); it kept changing concurrently. Re-read the analysis and try again.`,
+  );
+  if (lastConflict !== undefined) {
+    (finalError as Error & { cause?: unknown }).cause = lastConflict;
+  }
+  throw finalError;
+}
+
 export async function listAnalysisRevisions(
   analysisId: string,
   ctx: AccessCtx,