@designcrowd/library.brand-page 6.0.11 → 6.0.13

package/src/metadata-builder/builders/item-id-utils.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from 'vitest';
+import {
+  END_ITEM_ANCHOR,
+  ensureBrandPageItemIds,
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
+import type { BrandPageModel } from '../../brand-page/models';
+
+type Item = { id?: string; label: string };
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const items = (...labels: string[]): Item[] =>
+  labels.map((label) => ({ id: label, label }));
+
+const labels = (list: Item[]): string[] => list.map((i) => i.label);
+
+describe('generateItemId', () => {
+  it('returns unique uuid-shaped ids', () => {
+    const a = generateItemId();
+    const b = generateItemId();
+
+    expect(a).not.toBe(b);
+    expect(a).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+});
+
+describe('ensureItemIds', () => {
+  it('backfills only the items missing an id, preserving existing ones', () => {
+    const list: Item[] = [
+      { id: 'keep', label: 'a' },
+      { label: 'b' },
+      { id: '', label: 'c' },
+    ];
+
+    ensureItemIds(list);
+
+    expect(list[0].id).toBe('keep');
+    expect(list[1].id).toBeTruthy();
+    expect(list[2].id).toBeTruthy();
+    expect(new Set(list.map((i) => i.id)).size).toBe(3);
+  });
+
+  it('is a no-op for undefined', () => {
+    expect(() => ensureItemIds(undefined)).not.toThrow();
+  });
+});
+
+describe('removeItemsByIds', () => {
+  it('removes by id regardless of order (no index shifting)', () => {
+    const result = removeItemsByIds(items('a', 'b', 'c', 'd'), ['c', 'a']);
+
+    expect(labels(result)).toEqual(['b', 'd']);
+  });
+
+  it('returns the list unchanged when no ids given', () => {
+    const list = items('a', 'b');
+
+    expect(removeItemsByIds(list, undefined)).toBe(list);
+    expect(removeItemsByIds(list, [])).toBe(list);
+  });
+
+  it('returns [] for undefined items', () => {
+    expect(removeItemsByIds(undefined, ['x'])).toEqual([]);
+  });
+});
+
+describe('repositionItemByAnchor', () => {
+  it('appends a new item when no anchor is given', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+
+  it('leaves an existing item in place when no anchor is given', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[1], undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('inserts a new item before the anchor id', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'b');
+
+    expect(labels(list)).toEqual(['a', 'new', 'b', 'c']);
+  });
+
+  it('moves an existing item before the anchor id', () => {
+    const list = items('a', 'b', 'c', 'd');
+
+    // move 'd' before 'b'
+    repositionItemByAnchor(list, list[3], 'b');
+
+    expect(labels(list)).toEqual(['a', 'd', 'b', 'c']);
+  });
+
+  it('moves an existing item to the end with the __end__ sentinel', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[0], END_ITEM_ANCHOR);
+
+    expect(labels(list)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('falls through to the end when the anchor id is not found', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'missing');
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+});
+
+describe('ensureBrandPageItemIds', () => {
+  const makeModel = (): BrandPageModel =>
+    ({
+      pages: [
+        {
+          contents: [
+            {
+              type: 'image-gallery',
+              images: [{ imageUrl: 'a' }, { imageUrl: 'b' }],
+            },
+            {
+              type: 'testimonial-section',
+              items: [{ id: 'keep-me', name: 'X' }, { name: 'Y' }],
+            },
+            { type: 'text', textItems: [{ text: 'hi' }] },
+            { type: 'social-links', links: [{ url: 'u' }] },
+            { type: 'divider-section' }, // no item arrays — must not throw
+          ],
+        },
+      ],
+      pageFooterDesktop: { socialLinks: [{ url: 'f' }] },
+      pageFooterMobile: { socialLinks: [{ url: 'm' }] },
+    }) as unknown as BrandPageModel;
+
+  it('stamps a uuid id onto every id-less nested item across sections + footer', () => {
+    const model = makeModel();
+
+    ensureBrandPageItemIds(model);
+
+    const c = model.pages[0].contents as any[];
+
+    expect(c[0].images[0].id).toMatch(UUID_RE);
+    expect(c[0].images[1].id).toMatch(UUID_RE);
+    expect(c[1].items[1].id).toMatch(UUID_RE);
+    expect(c[2].textItems[0].id).toMatch(UUID_RE);
+    expect(c[3].links[0].id).toMatch(UUID_RE);
+    expect((model.pageFooterDesktop as any).socialLinks[0].id).toMatch(UUID_RE);
+    expect((model.pageFooterMobile as any).socialLinks[0].id).toMatch(UUID_RE);
+  });
+
+  it('preserves existing ids (idempotent)', () => {
+    const model = makeModel();
+
+    ensureBrandPageItemIds(model);
+    const first = (model.pages[0].contents as any[])[1].items[0].id;
+
+    ensureBrandPageItemIds(model);
+    const second = (model.pages[0].contents as any[])[1].items[0].id;
+
+    expect(first).toBe('keep-me');
+    expect(second).toBe('keep-me');
+  });
+
+  it('does not throw on an empty / partial model', () => {
+    expect(() => ensureBrandPageItemIds({} as BrandPageModel)).not.toThrow();
+    expect(() =>
+      ensureBrandPageItemIds({ pages: [] } as unknown as BrandPageModel),
+    ).not.toThrow();
+  });
+});

package/src/metadata-builder/builders/item-id-utils.ts

@@ -0,0 +1,117 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { BrandPageModel } from '../../brand-page/models';
+
+/**
+ * Sentinel anchor meaning "the end of the list", mirroring the section-level
+ * `move_before_content_id: "__end__"` convention used in base-section-builder.
+ */
+export const END_ITEM_ANCHOR = '__end__';
+
+/** Generate a stable item id. Mirrors section-level `uuid.v4()` id generation. */
+export const generateItemId = (): string => uuidv4();
+
+/**
+ * Walk an entire BrandPageModel and backfill a stable uuid `id` onto every
+ * nested array item that lacks one (gallery images, images/shapes/testimonial
+ * items, text items, social links, and footer social links).
+ *
+ * BP-5603: this must run BEFORE the model is minified for the AI, so the same
+ * id the AI is shown (and copies into `item_id`) is the one the executor later
+ * matches. The maker holds a single live model instance for both the minify
+ * and the apply step, so mutating it here makes the ids round-trip; they then
+ * persist on the next save. Idempotent — existing ids are preserved.
+ */
+export const ensureBrandPageItemIds = (model: BrandPageModel): void => {
+  const ensureContentItemIds = (content: Record<string, unknown>): void => {
+    // Every array field that the minifier surfaces as a list of items.
+    for (const field of ['images', 'items', 'textItems', 'links'] as const) {
+      const arr = content[field];
+
+      if (Array.isArray(arr)) ensureItemIds(arr as { id?: string }[]);
+    }
+  };
+
+  for (const page of model.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      ensureContentItemIds(content as unknown as Record<string, unknown>);
+    }
+  }
+
+  ensureItemIds(model.pageFooterDesktop?.socialLinks);
+  ensureItemIds(model.pageFooterMobile?.socialLinks);
+};
+
+/**
+ * Backfill ids onto any items missing one. Per BP-5603 this runs in the
+ * metadata builder when a section is processed, so the persisted metadata
+ * returned to the client gains stable ids that subsequent AI tool calls can
+ * reference. Mutates in place.
+ */
+export const ensureItemIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+): void => {
+  if (!items) return;
+
+  for (const item of items) {
+    if (!item.id) item.id = generateItemId();
+  }
+};
+
+/**
+ * Remove items whose id appears in `ids`. Order-independent (no descending
+ * index sort needed) — the whole point of the id-based migration. Items
+ * without an id are never removed by id.
+ */
+export const removeItemsByIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+  ids: string[] | undefined,
+): T[] => {
+  if (!items?.length) return items ?? [];
+
+  if (!ids?.length) return items;
+
+  const toRemove = new Set(ids);
+
+  return items.filter((item) => !item.id || !toRemove.has(item.id));
+};
+
+/**
+ * Position `item` within `items` relative to an anchor id — the item-level
+ * mirror of base-section-builder's `moveContent`:
+ *
+ * - `moveBeforeItemId === undefined`  → leave an existing item where it is;
+ *   append a new (not-yet-present) item to the end.
+ * - `moveBeforeItemId === "__end__"`  → move/insert at the very end.
+ * - anchor id found                   → insert immediately before it.
+ * - anchor id not found               → fall through to the end (same
+ *   forgiving behaviour as `moveContent`).
+ *
+ * Mutates `items` in place. `item` may be an existing element of `items`
+ * (a move) or a brand-new object (an insert).
+ */
+export const repositionItemByAnchor = <T extends { id?: string }>(
+  items: T[],
+  item: T,
+  moveBeforeItemId: string | undefined,
+): void => {
+  const currentIndex = items.indexOf(item);
+
+  if (moveBeforeItemId === undefined) {
+    if (currentIndex === -1) items.push(item);
+
+    return;
+  }
+
+  if (currentIndex !== -1) items.splice(currentIndex, 1);
+
+  const anchorIndex =
+    moveBeforeItemId === END_ITEM_ANCHOR
+      ? -1
+      : items.findIndex((i) => i.id === moveBeforeItemId);
+
+  if (anchorIndex !== -1) {
+    items.splice(anchorIndex, 0, item);
+  } else {
+    items.push(item);
+  }
+};

package/src/metadata-builder/builders/move-page-builder.ts

@@ -0,0 +1,227 @@
+import type { BrandPageModel, NavOrder } from '../../brand-page/models';
+import { getPageSlugFromPageTitle } from '../../brand-page-maker/utils/slug.util';
+import {
+  BaseMetadataBuilder,
+  type BuilderResult,
+  type MetadataBuilderRequest,
+} from '../models';
+import type { Logger } from '../logger';
+import {
+  detachOrder,
+  findOrderAnywhere,
+  findParentRouteId,
+  getSiblingSlugsAtDepth,
+  syncPagesWithNavOrders,
+} from './nav-utils';
+
+export interface MovePagePayload {
+  /** The page to move (resolved from page_id). */
+  pageId: string;
+  /**
+   * Destination parent: a page_id to nest under, or null/undefined for top-level.
+   * Analogous to move_section's target_page_id.
+   */
+  parentPageId?: string | null;
+  /**
+   * Position anchor at the destination level: the page_id of the sibling to
+   * insert before, or "__end__" to append. Omitted/null → append at end.
+   * Analogous to move_section's move_before_content_id.
+   */
+  moveBeforePageId?: string | null;
+}
+
+export class MovePageBuilder extends BaseMetadataBuilder<MovePagePayload> {
+  constructor(
+    request: MetadataBuilderRequest<MovePagePayload>,
+    logger?: Logger,
+  ) {
+    super(request, logger);
+  }
+
+  async validateAsync(): Promise<{ errors: string[] }> {
+    const errors: string[] = [];
+    const payload = this.request.payload;
+
+    if (!payload?.pageId) {
+      errors.push('pageId is required for move_page');
+    }
+
+    return { errors };
+  }
+
+  async buildAsync(model: BrandPageModel): Promise<BuilderResult> {
+    this.log('Build called');
+
+    const validation = await this.validateAsync();
+
+    if (validation.errors.length) {
+      return { request: this.request, model, errors: validation.errors };
+    }
+
+    const { pageId, parentPageId, moveBeforePageId } = this.request.payload!;
+
+    // Build lookup: pageId → NavRoute.
+    const routeByPageId = new Map(model.nav.routes.map((r) => [r.pageId, r]));
+
+    // --- Find the target route ---
+    const targetRoute = routeByPageId.get(pageId);
+
+    if (!targetRoute) {
+      return {
+        request: this.request,
+        model,
+        errors: [`Page with ID "${pageId}" not found`],
+      };
+    }
+
+    const targetRouteId = targetRoute.id;
+
+    // Find the NavOrder for the target (must exist in the tree).
+    const targetOrder = findOrderAnywhere(model.nav.orders, targetRouteId);
+
+    if (!targetOrder) {
+      return {
+        request: this.request,
+        model,
+        errors: [`NavOrder for page "${pageId}" not found in nav.orders`],
+      };
+    }
+
+    // --- GUARD: parent cannot equal target ---
+    if (parentPageId && parentPageId === pageId) {
+      return {
+        request: this.request,
+        model,
+        errors: [`A page cannot be nested under itself`],
+      };
+    }
+
+    // --- GUARD: home page (orders[0]) cannot be nested ---
+    const homeRouteId = model.nav.orders[0]?.routeId;
+
+    if (parentPageId && homeRouteId === targetRouteId) {
+      return {
+        request: this.request,
+        model,
+        errors: [`Home page "${pageId}" cannot be nested under another page`],
+      };
+    }
+
+    // --- Resolve destination level ---
+    let destinationOrders: NavOrder[];
+
+    if (parentPageId) {
+      const parentRoute = routeByPageId.get(parentPageId);
+
+      if (!parentRoute) {
+        return {
+          request: this.request,
+          model,
+          errors: [`Parent page with ID "${parentPageId}" not found`],
+        };
+      }
+
+      // GUARD: parent must be a root-level page (depth-1 cap).
+      const isParentAtRoot = model.nav.orders.some(
+        (o) => o.routeId === parentRoute.id,
+      );
+
+      if (!isParentAtRoot) {
+        return {
+          request: this.request,
+          model,
+          errors: [
+            `Parent page "${parentPageId}" is itself a subpage — nesting beyond depth 1 is not supported`,
+          ],
+        };
+      }
+
+      const parentOrder = findOrderAnywhere(model.nav.orders, parentRoute.id);
+
+      // GUARD: target page must not have its own subRoutes when being nested.
+      if (targetOrder.subRoutes.length > 0) {
+        return {
+          request: this.request,
+          model,
+          errors: [
+            `Page "${pageId}" has subpages and cannot itself be nested under another page`,
+          ],
+        };
+      }
+
+      destinationOrders = parentOrder!.subRoutes;
+    } else {
+      // Moving to top level (un-nest or reorder at root).
+      destinationOrders = model.nav.orders;
+    }
+
+    // Record the old parent before any mutation for slug recompute.
+    const oldParentRouteId = findParentRouteId(model.nav.orders, targetRouteId);
+
+    // Detach the target from its current position.
+    detachOrder(model.nav.orders, targetRouteId);
+
+    // --- Resolve insertion index ---
+    const insertIndex = this.resolveIndex(
+      destinationOrders,
+      moveBeforePageId,
+      routeByPageId,
+    );
+
+    destinationOrders.splice(insertIndex, 0, targetOrder);
+
+    // --- Slug recompute only when parent changed ---
+    const newParentRouteId =
+      findParentRouteId(model.nav.orders, targetRouteId) ?? undefined;
+
+    // After detach+re-insert, undefined means root.
+    const effectiveOldParent = oldParentRouteId ?? undefined;
+
+    if (newParentRouteId !== effectiveOldParent) {
+      const siblingSlugs = getSiblingSlugsAtDepth(
+        model,
+        newParentRouteId,
+        targetRouteId,
+      );
+
+      targetRoute.pageSlug = getPageSlugFromPageTitle(
+        targetRoute.displayName,
+        siblingSlugs,
+      );
+    }
+
+    syncPagesWithNavOrders(model);
+
+    this.log({
+      message: `Moved page "${pageId}" — parent: ${parentPageId ?? 'root'}, before: ${moveBeforePageId ?? 'end'}`,
+    });
+
+    return { request: this.request, model };
+  }
+
+  /**
+   * Resolve the insertion index within destinationOrders.
+   *
+   * moveBeforePageId anchors by pageId of a sibling at that level.
+   * "__end__" or omitted/null → append. Unknown anchor → append.
+   */
+  private resolveIndex(
+    destinationOrders: NavOrder[],
+    moveBeforePageId: string | null | undefined,
+    routeByPageId: Map<string, { id: string }>,
+  ): number {
+    if (!moveBeforePageId || moveBeforePageId === '__end__') {
+      return destinationOrders.length;
+    }
+
+    const anchorRoute = routeByPageId.get(moveBeforePageId);
+
+    if (!anchorRoute) return destinationOrders.length;
+
+    const idx = destinationOrders.findIndex(
+      (o) => o.routeId === anchorRoute.id,
+    );
+
+    return idx !== -1 ? idx : destinationOrders.length;
+  }
+}

package/src/metadata-builder/builders/nav-utils.ts

@@ -0,0 +1,141 @@
+import type { BrandPageModel, NavOrder } from '../../brand-page/models';
+
+/**
+ * DFS walk of nav.orders (recurse subRoutes), returning every routeId in visit order.
+ */
+const dfsRouteIds = (orders: NavOrder[]): string[] => {
+  const ids: string[] = [];
+
+  for (const order of orders) {
+    ids.push(order.routeId);
+    ids.push(...dfsRouteIds(order.subRoutes));
+  }
+
+  return ids;
+};
+
+/**
+ * Resync model.pages[] to match the DFS walk of model.nav.orders.
+ * Pages not referenced in nav are appended at the end (defensive).
+ * Mutates and returns model.pages in place.
+ */
+export const syncPagesWithNavOrders = (
+  model: BrandPageModel,
+): BrandPageModel['pages'] => {
+  const routeIds = dfsRouteIds(model.nav.orders);
+
+  // Build a map from pageId to its nav position so we can sort pages by encounter order.
+  const routeById = new Map(model.nav.routes.map((r) => [r.id, r]));
+
+  // Map from pageId → DFS index (using route→pageId lookup).
+  const routeIdToDfsIndex = new Map(routeIds.map((rid, i) => [rid, i]));
+
+  // Convert nav routeId order to pageId order.
+  const pageIdOrder = new Map<string, number>();
+
+  for (const [routeId, idx] of routeIdToDfsIndex) {
+    const route = routeById.get(routeId);
+
+    if (route) {
+      pageIdOrder.set(route.pageId, idx);
+    }
+  }
+
+  const navMax = routeIds.length;
+
+  model.pages = [...model.pages].sort((a, b) => {
+    const ia = pageIdOrder.has(a.id) ? pageIdOrder.get(a.id)! : navMax;
+    const ib = pageIdOrder.has(b.id) ? pageIdOrder.get(b.id)! : navMax;
+
+    return ia - ib;
+  });
+
+  return model.pages;
+};
+
+/**
+ * Find a NavOrder by routeId anywhere in the tree (root + subRoutes, recursive).
+ */
+export const findOrderAnywhere = (
+  orders: NavOrder[],
+  routeId: string,
+): NavOrder | undefined => {
+  for (const order of orders) {
+    if (order.routeId === routeId) return order;
+
+    const found = findOrderAnywhere(order.subRoutes, routeId);
+
+    if (found) return found;
+  }
+
+  return undefined;
+};
+
+/**
+ * Find the routeId of the parent that contains the target as a direct child in subRoutes.
+ * Returns undefined when the target is a root order.
+ */
+export const findParentRouteId = (
+  orders: NavOrder[],
+  targetRouteId: string,
+  _parentId?: string,
+): string | undefined => {
+  for (const order of orders) {
+    if (order.subRoutes.some((sr) => sr.routeId === targetRouteId)) {
+      return order.routeId;
+    }
+
+    const found = findParentRouteId(
+      order.subRoutes,
+      targetRouteId,
+      order.routeId,
+    );
+
+    if (found !== undefined) return found;
+  }
+
+  return undefined;
+};
+
+/**
+ * Splice the NavOrder with routeId from wherever it lives (root or any subRoutes), in place.
+ */
+export const detachOrder = (orders: NavOrder[], routeId: string): void => {
+  const idx = orders.findIndex((o) => o.routeId === routeId);
+
+  if (idx !== -1) {
+    orders.splice(idx, 1);
+
+    return;
+  }
+
+  for (const order of orders) {
+    detachOrder(order.subRoutes, routeId);
+  }
+};
+
+/**
+ * Return the slugs of all routes that are direct children at the same depth as parentRouteId.
+ * - parentRouteId === undefined → root orders.
+ * - excludeRouteId is omitted from the result (pass the route being renamed/moved).
+ */
+export const getSiblingSlugsAtDepth = (
+  model: BrandPageModel,
+  parentRouteId: string | undefined,
+  excludeRouteId: string,
+): string[] => {
+  const siblingOrders =
+    parentRouteId === undefined
+      ? model.nav.orders
+      : (findOrderAnywhere(model.nav.orders, parentRouteId)?.subRoutes ?? []);
+
+  const siblingRouteIds = new Set(
+    siblingOrders
+      .filter((o) => o.routeId !== excludeRouteId)
+      .map((o) => o.routeId),
+  );
+
+  return model.nav.routes
+    .filter((r) => siblingRouteIds.has(r.id))
+    .map((r) => r.pageSlug);
+};