@dyrected/core 2.15.0 → 2.17.0

package/dist/index.js

@@ -1845,6 +1845,21 @@ var DyrectedAIError = class _DyrectedAIError extends Error {
   }
 };
 
+// src/types/navigation.ts
+function defineWorkspace(options) {
+  return options;
+}
+var CURRENT_NAV_PREFERENCES_VERSION = 1;
+var DEFAULT_USER_NAV_PREFERENCES = {
+  _version: CURRENT_NAV_PREFERENCES_VERSION,
+  pinned: [],
+  hidden: [],
+  groupOrder: [],
+  itemOrder: {},
+  groups: [],
+  items: []
+};
+
 // src/auth/token.ts
 import { SignJWT, jwtVerify, decodeJwt } from "jose";
 
@@ -3363,6 +3378,134 @@ function assertValidDeclarativeAccessInConfig(config, source = "config") {
   throw new ConfigValidationError(source, diagnostics);
 }
 
+// src/utils/id.ts
+import { randomBytes, randomUUID } from "crypto";
+var NANOID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_-";
+var BASE62_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var COMMON_SLUG_PREFIXES = {
+  users: "usr",
+  members: "mem",
+  accounts: "acc",
+  applications: "app",
+  customers: "cus",
+  products: "prd",
+  orders: "ord",
+  reports: "rpt",
+  sessions: "ses",
+  transactions: "txn",
+  wallets: "wal",
+  media: "med",
+  files: "fil",
+  posts: "post",
+  pages: "page",
+  tags: "tag",
+  categories: "cat",
+  comments: "com"
+};
+function nanoid(size = 21, alphabet = NANOID_ALPHABET) {
+  const mask = (2 << 31 - Math.clz32(alphabet.length - 1 | 1)) - 1;
+  const step = Math.ceil(1.6 * mask * size / alphabet.length);
+  let id = "";
+  while (true) {
+    const bytes = randomBytes(step);
+    for (let i = 0; i < step; i++) {
+      const byte = bytes[i] & mask;
+      if (alphabet[byte]) {
+        id += alphabet[byte];
+        if (id.length === size) return id;
+      }
+    }
+  }
+}
+function encodeUlidTime(now2, len = 10) {
+  let str = "";
+  let time = Math.floor(now2);
+  for (let i = len - 1; i >= 0; i--) {
+    const mod = time % 32;
+    str = CROCKFORD_BASE32[mod] + str;
+    time = (time - mod) / 32;
+  }
+  return str;
+}
+function encodeUlidRandom(bytes) {
+  let str = "";
+  let bitBuffer = 0;
+  let bitsInBuffer = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    bitBuffer = bitBuffer << 8 | bytes[i];
+    bitsInBuffer += 8;
+    while (bitsInBuffer >= 5) {
+      bitsInBuffer -= 5;
+      const index = bitBuffer >> bitsInBuffer & 31;
+      str += CROCKFORD_BASE32[index];
+    }
+  }
+  return str;
+}
+function ulid(seedTime = Date.now()) {
+  const timePart = encodeUlidTime(seedTime);
+  const randPart = encodeUlidRandom(randomBytes(10));
+  return timePart + randPart;
+}
+function uuid() {
+  return randomUUID();
+}
+function resolvePrefix(slug, explicitPrefix) {
+  if (explicitPrefix && typeof explicitPrefix === "string" && explicitPrefix.trim().length > 0) {
+    const cleaned = explicitPrefix.trim().toLowerCase().replace(/[^a-z0-9_]/g, "");
+    if (cleaned.length > 0) return cleaned;
+  }
+  if (!slug || typeof slug !== "string") return "col";
+  const s = slug.trim().toLowerCase();
+  if (COMMON_SLUG_PREFIXES[s]) return COMMON_SLUG_PREFIXES[s];
+  const pieces = s.split(/[-_]/).filter(Boolean);
+  if (pieces.length > 1 && pieces[0].length >= 2) {
+    const first2 = pieces[0].replace(/[^a-z0-9]/g, "");
+    if (first2.length >= 2) return first2.slice(0, 4);
+  }
+  const cleanWord = s.replace(/[^a-z0-9]/g, "");
+  if (cleanWord.length <= 4) return cleanWord || "col";
+  return cleanWord.slice(0, 3) || "col";
+}
+function prefixedId(prefix = "col", size = 16) {
+  const cleanPrefix = (prefix || "col").toLowerCase().replace(/[^a-z0-9_]/g, "") || "col";
+  return `${cleanPrefix}_${nanoid(size, BASE62_ALPHABET)}`;
+}
+function generateId(options) {
+  if (typeof options === "string") {
+    return prefixedId(resolvePrefix(options));
+  }
+  const opts = options || {};
+  const type = opts.type || "prefixed-nanoid";
+  switch (type) {
+    case "uuid":
+      return uuid();
+    case "ulid":
+      return ulid();
+    case "nanoid":
+      return nanoid(opts.size || 21);
+    case "prefixed-nanoid":
+    default:
+      return prefixedId(opts.prefix || "col", opts.size || 16);
+  }
+}
+function generateDocumentId(collectionOrSlug) {
+  if (!collectionOrSlug) {
+    return prefixedId("col");
+  }
+  if (typeof collectionOrSlug === "string") {
+    const prefix2 = resolvePrefix(collectionOrSlug);
+    return prefixedId(prefix2);
+  }
+  if (typeof collectionOrSlug.idGenerator === "function") {
+    return collectionOrSlug.idGenerator(collectionOrSlug.slug);
+  }
+  const type = collectionOrSlug.idType || "prefixed-nanoid";
+  const prefix = resolvePrefix(collectionOrSlug.slug, collectionOrSlug.idPrefix);
+  return generateId({ prefix, type });
+}
+
 // src/utils/config.ts
 var AUDIT_COLLECTION_SLUG = "__audit";
 var SYSTEM_FIELDS = [
@@ -3593,7 +3736,33 @@ function normalizeConfig(config) {
           }
         ];
       }
+      if (!existingFieldNames.has("__preferences")) {
+        fields = [
+          ...fields,
+          {
+            name: "__preferences",
+            type: "json",
+            label: "Preferences",
+            promoted: true,
+            admin: {
+              hidden: true,
+              readOnly: true
+            }
+          }
+        ];
+      }
       fields = fields.map((field) => {
+        if (field.name === "__preferences") {
+          return {
+            ...field,
+            promoted: true,
+            admin: {
+              ...field.admin || {},
+              hidden: true,
+              readOnly: true
+            }
+          };
+        }
         if (field.name === "email") {
           return {
             ...field,
@@ -3684,11 +3853,31 @@ function normalizeConfig(config) {
     }
     const updatedFieldNames = new Set(fields.map((f) => f.name));
     const fieldsToInject = SYSTEM_FIELDS.filter((f) => !updatedFieldNames.has(f.name));
+    const indexedFieldNames = /* @__PURE__ */ new Set();
+    if (col.indexes) {
+      for (const idx of col.indexes) {
+        if (Array.isArray(idx.fields)) {
+          for (const f of idx.fields) {
+            indexedFieldNames.add(f);
+          }
+        }
+      }
+    }
+    const allFields = [...fields, ...fieldsToInject].map((field) => {
+      if (field.unique || field.name && indexedFieldNames.has(field.name)) {
+        return { ...field, promoted: true };
+      }
+      return field;
+    });
     const workflow = col.workflow || (col.drafts ? simplePublishingWorkflow() : void 0);
+    const idPrefix = col.idPrefix || resolvePrefix(col.slug);
+    const idType = col.idType || "prefixed-nanoid";
     return {
       ...col,
+      idPrefix,
+      idType,
       workflow,
-      fields: [...fields, ...fieldsToInject]
+      fields: allFields
     };
   });
   const hasAuditCollection = normalizedCollections.some((col) => col.slug === AUDIT_COLLECTION_SLUG);
@@ -3748,6 +3937,17 @@ var ConflictError = class _ConflictError extends DyrectedError {
     Object.setPrototypeOf(this, _ConflictError.prototype);
   }
 };
+var DuplicateKeyError = class _DuplicateKeyError extends ConflictError {
+  field;
+  value;
+  constructor(message, options) {
+    super(message);
+    this.name = "DuplicateKeyError";
+    this.field = options?.field;
+    this.value = options?.value;
+    Object.setPrototypeOf(this, _DuplicateKeyError.prototype);
+  }
+};
 
 // src/utils/parse-where.ts
 function assertNever(op, context) {
@@ -6369,6 +6569,525 @@ function sanitizeDocForAI(options) {
   return result;
 }
 
+// src/utils/navigation-reconciler.ts
+var normalizeKey = (val) => (val || "").toLowerCase().replace(/[^a-z0-9]/g, "-");
+function reconcileNavigation(baseTree, prefs, schemas, options) {
+  if (!baseTree) {
+    return {
+      groups: [],
+      ungrouped: [],
+      pinnedItems: []
+    };
+  }
+  const includeHidden = options?.includeHidden ?? false;
+  const effectivePrefs = prefs || DEFAULT_USER_NAV_PREFERENCES;
+  const hiddenSet = new Set(effectivePrefs.hidden || []);
+  const knownCollectionSlugs = new Set((schemas?.collections || []).map((c) => c.slug));
+  const knownGlobalSlugs = new Set((schemas?.globals || []).map((g) => g.slug));
+  const groupsList = [];
+  const findGroup = (query) => {
+    const qNorm = normalizeKey(query);
+    return groupsList.find(
+      (g) => g.id === query || g.slug === query || g.name === query || normalizeKey(g.id) === qNorm || normalizeKey(g.slug) === qNorm || normalizeKey(g.name) === qNorm
+    );
+  };
+  for (const g of baseTree.groups || []) {
+    groupsList.push({
+      ...g,
+      items: (g.items || []).map((item) => ({ ...item }))
+    });
+  }
+  for (const ug of effectivePrefs.groups || []) {
+    const existing = findGroup(ug.slug || ug.name);
+    if (!existing) {
+      groupsList.push({
+        id: ug.slug ? `group_${ug.slug}` : `group_${normalizeKey(ug.name)}`,
+        name: ug.name,
+        slug: ug.slug || normalizeKey(ug.name),
+        icon: ug.icon || "Folder",
+        defaultExpanded: ug.defaultExpanded ?? true,
+        order: ug.order ?? 100,
+        items: []
+      });
+    }
+  }
+  for (const itemOpt of effectivePrefs.items || []) {
+    const targetGroup = typeof itemOpt.group === "object" ? itemOpt.group?.name : itemOpt.group;
+    const groupKey = targetGroup || "Custom";
+    let group = findGroup(groupKey);
+    if (!group) {
+      group = {
+        id: `group_${normalizeKey(groupKey)}`,
+        name: groupKey,
+        slug: normalizeKey(groupKey),
+        icon: "Folder",
+        defaultExpanded: true,
+        order: 99,
+        items: []
+      };
+      groupsList.push(group);
+    }
+    const itemId = itemOpt.slug ? `workspace_${itemOpt.slug}` : itemOpt.collection ? `collection_${itemOpt.collection}` : `custom_${Math.random()}`;
+    for (const otherGroup of groupsList) {
+      if (otherGroup !== group) {
+        otherGroup.items = otherGroup.items.filter((i) => i.slug !== itemOpt.slug && i.id !== itemId);
+      }
+    }
+    const existingIndex = group.items.findIndex((i) => i.id === itemId || i.slug === itemOpt.slug);
+    const existingItem = existingIndex >= 0 ? group.items[existingIndex] : void 0;
+    const col = schemas?.collections?.find((c) => c.slug === itemOpt.collection);
+    const colViews = col?.views || [];
+    const baseViews = existingItem?.views || [];
+    const userViews = itemOpt.views || [];
+    const userViewSlugs = new Set(userViews.map((v) => v.slug));
+    let mergedViews = [
+      ...baseViews.filter((v) => !userViewSlugs.has(v.slug)),
+      ...userViews
+    ];
+    if (mergedViews.length === 0 && itemOpt.collection) {
+      if (colViews.length > 0) {
+        mergedViews = [...colViews];
+      } else {
+        mergedViews = [
+          {
+            slug: "default",
+            label: col?.label || col?.labels?.plural || itemOpt.label || "All Records",
+            layout: "table",
+            collection: itemOpt.collection
+          }
+        ];
+      }
+    }
+    mergedViews = mergedViews.map((v) => ({
+      ...v,
+      collection: v.collection || itemOpt.collection || existingItem?.collection
+    }));
+    const compiledItem = {
+      id: itemId,
+      type: itemOpt.slug ? "workspace" : itemOpt.collection ? "collection" : itemOpt.global ? "global" : "workspace",
+      slug: itemOpt.slug || itemOpt.collection || itemOpt.global || "item",
+      label: itemOpt.label || itemOpt.slug || "Item",
+      icon: itemOpt.icon || existingItem?.icon || col?.admin?.icon || "Briefcase",
+      group: group.name,
+      order: itemOpt.order ?? existingItem?.order ?? 100,
+      views: mergedViews,
+      collection: itemOpt.collection || existingItem?.collection,
+      global: itemOpt.global || existingItem?.global,
+      badge: itemOpt.badge || existingItem?.badge,
+      access: itemOpt.access || existingItem?.access
+    };
+    if (existingIndex >= 0) {
+      group.items[existingIndex] = compiledItem;
+    } else {
+      group.items.push(compiledItem);
+    }
+  }
+  const allAvailableItems = [];
+  const reconciledGroups = [];
+  for (const group of groupsList) {
+    const isGroupHidden = hiddenSet.has(group.id) || !!group.slug && hiddenSet.has(group.slug) || hiddenSet.has(group.name);
+    if (!includeHidden && isGroupHidden) {
+      continue;
+    }
+    const visibleItems = [];
+    for (const item of group.items) {
+      const isItemHidden = hiddenSet.has(item.id) || !!item.slug && hiddenSet.has(item.slug);
+      if (!includeHidden && isItemHidden) {
+        continue;
+      }
+      const allViews = item.views || [];
+      const visibleViews = includeHidden ? allViews : allViews.filter((v) => {
+        const compoundKey = `${item.slug}_${v.slug}`;
+        return !hiddenSet.has(compoundKey) && !hiddenSet.has(v.slug);
+      });
+      let isTombstone = false;
+      if (schemas && schemas.collections && schemas.collections.length > 0) {
+        if (item.collection && !knownCollectionSlugs.has(item.collection)) {
+          isTombstone = true;
+        }
+      }
+      if (schemas && schemas.globals && schemas.globals.length > 0) {
+        if (item.global && !knownGlobalSlugs.has(item.global)) {
+          isTombstone = true;
+        }
+      }
+      const processedItem = {
+        ...item,
+        views: visibleViews,
+        ...isTombstone ? { isTombstone: true } : {}
+      };
+      visibleItems.push(processedItem);
+      allAvailableItems.push(processedItem);
+    }
+    const groupKey = group.slug || group.name;
+    const itemOrderList = effectivePrefs.itemOrder?.[group.id] || effectivePrefs.itemOrder?.[groupKey];
+    if (itemOrderList && itemOrderList.length > 0) {
+      visibleItems.sort((a, b) => {
+        const aIdx = itemOrderList.indexOf(a.id) >= 0 ? itemOrderList.indexOf(a.id) : a.slug ? itemOrderList.indexOf(a.slug) : -1;
+        const bIdx = itemOrderList.indexOf(b.id) >= 0 ? itemOrderList.indexOf(b.id) : b.slug ? itemOrderList.indexOf(b.slug) : -1;
+        if (aIdx >= 0 && bIdx >= 0) return aIdx - bIdx;
+        if (aIdx >= 0) return -1;
+        if (bIdx >= 0) return 1;
+        return (a.order ?? 100) - (b.order ?? 100);
+      });
+    } else {
+      visibleItems.sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+    }
+    reconciledGroups.push({
+      ...group,
+      items: visibleItems
+    });
+  }
+  if (effectivePrefs.groupOrder && effectivePrefs.groupOrder.length > 0) {
+    reconciledGroups.sort((a, b) => {
+      const aIdx = effectivePrefs.groupOrder.indexOf(a.id) >= 0 ? effectivePrefs.groupOrder.indexOf(a.id) : a.slug ? effectivePrefs.groupOrder.indexOf(a.slug) : effectivePrefs.groupOrder.indexOf(a.name);
+      const bIdx = effectivePrefs.groupOrder.indexOf(b.id) >= 0 ? effectivePrefs.groupOrder.indexOf(b.id) : b.slug ? effectivePrefs.groupOrder.indexOf(b.slug) : effectivePrefs.groupOrder.indexOf(b.name);
+      if (aIdx >= 0 && bIdx >= 0) return aIdx - bIdx;
+      if (aIdx >= 0) return -1;
+      if (bIdx >= 0) return 1;
+      return (a.order ?? 100) - (b.order ?? 100);
+    });
+  } else {
+    reconciledGroups.sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+  }
+  const reconciledUngrouped = (baseTree.ungrouped || []).filter((item) => {
+    const isItemHidden = hiddenSet.has(item.id) || !!item.slug && hiddenSet.has(item.slug);
+    return includeHidden || !isItemHidden;
+  }).map((item) => {
+    const allViews = item.views || [];
+    const visibleViews = includeHidden ? allViews : allViews.filter((v) => {
+      const compoundKey = `${item.slug}_${v.slug}`;
+      return !hiddenSet.has(compoundKey) && !hiddenSet.has(v.slug);
+    });
+    const processed = { ...item, views: visibleViews };
+    allAvailableItems.push(processed);
+    return processed;
+  });
+  const pinnedItems = [];
+  for (const pin of effectivePrefs.pinned || []) {
+    const match = allAvailableItems.find((i) => i.slug === pin.slug || i.id === pin.slug);
+    if (match) {
+      pinnedItems.push({
+        ...match,
+        id: `pin_${match.id}`,
+        label: pin.label || match.label,
+        icon: pin.icon || match.icon
+      });
+    } else {
+      pinnedItems.push({
+        id: `pin_${pin.slug}`,
+        type: pin.type,
+        slug: pin.slug,
+        label: pin.label || pin.slug,
+        icon: pin.icon || "Star",
+        order: 0,
+        views: []
+      });
+    }
+  }
+  return {
+    groups: reconciledGroups,
+    ungrouped: reconciledUngrouped,
+    pinnedItems
+  };
+}
+
+// src/utils/navigation.ts
+var RESERVED_NAVIGATION_SLUGS = /* @__PURE__ */ new Set([
+  "collections",
+  "globals",
+  "setup",
+  "api",
+  "login",
+  "logout",
+  "settings",
+  "admin",
+  "preferences",
+  "auth"
+]);
+function assertValidNavigationSlugs(navigation) {
+  for (const item of navigation) {
+    if (item.slug) {
+      const normalizedSlug = item.slug.toLowerCase().trim().replace(/^\//, "");
+      if (RESERVED_NAVIGATION_SLUGS.has(normalizedSlug)) {
+        throw new Error(
+          `[Dyrected Config] The slug '${item.slug}' in navigation item '${item.label || item.slug}' is a reserved system path and cannot be used as an operational workspace slug.`
+        );
+      }
+    }
+  }
+}
+function resolveGroupMeta(groupProp, defaultGroupName = "Collections") {
+  if (!groupProp) {
+    return { name: defaultGroupName };
+  }
+  if (typeof groupProp === "string") {
+    return { name: groupProp };
+  }
+  return { name: groupProp.name, meta: groupProp };
+}
+function compileNavigation(config) {
+  const collections = config.collections || [];
+  const globals = config.globals || [];
+  const explicitNav = config.admin?.navigation || [];
+  assertValidNavigationSlugs(explicitNav);
+  const collectionsBySlug = /* @__PURE__ */ new Map();
+  for (const col of collections) {
+    collectionsBySlug.set(col.slug, col);
+  }
+  const globalsBySlug = /* @__PURE__ */ new Map();
+  for (const gl of globals) {
+    globalsBySlug.set(gl.slug, gl);
+  }
+  const mentionedCollections = /* @__PURE__ */ new Set();
+  const mentionedGlobals = /* @__PURE__ */ new Set();
+  const injectedViewsByCollection = /* @__PURE__ */ new Map();
+  for (const item of explicitNav) {
+    if (item.addToCollection) {
+      const existing = injectedViewsByCollection.get(item.addToCollection) || [];
+      if (item.views && item.views.length > 0) {
+        injectedViewsByCollection.set(item.addToCollection, [...existing, ...item.views]);
+      }
+    }
+    if (item.collection) mentionedCollections.add(item.collection);
+    if (item.global) mentionedGlobals.add(item.global);
+  }
+  const groupMetadataMap = /* @__PURE__ */ new Map();
+  const itemsByGroup = /* @__PURE__ */ new Map();
+  const ungroupedItems = [];
+  const registerItem = (groupName, item) => {
+    if (!groupName) {
+      ungroupedItems.push(item);
+    } else {
+      const list = itemsByGroup.get(groupName) || [];
+      list.push(item);
+      itemsByGroup.set(groupName, list);
+    }
+  };
+  for (const item of explicitNav) {
+    if (item.addToCollection && !item.slug && !item.collection && !item.global && !item.dashboard && !item.href) {
+      continue;
+    }
+    const { name: groupName, meta: groupMeta } = resolveGroupMeta(item.group, void 0);
+    if (groupName && groupMeta) {
+      groupMetadataMap.set(groupName, { ...groupMetadataMap.get(groupName) || {}, ...groupMeta });
+    }
+    if (item.dashboard) {
+      registerItem(groupName, {
+        id: "dashboard",
+        type: "dashboard",
+        slug: "dashboard",
+        label: item.label || "Dashboard",
+        icon: item.icon || "LayoutDashboard",
+        group: groupName,
+        order: item.order ?? 0,
+        views: [],
+        access: item.access
+      });
+      continue;
+    }
+    if (item.collection) {
+      const col = collectionsBySlug.get(item.collection);
+      const combinedViews = [
+        ...col?.views || [],
+        ...injectedViewsByCollection.get(item.collection) || [],
+        ...item.views || []
+      ];
+      registerItem(groupName, {
+        id: item.slug || `collection_${item.collection}`,
+        type: item.slug ? "workspace" : "collection",
+        slug: item.slug || item.collection,
+        collection: item.collection,
+        label: item.label || col?.labels?.plural || item.collection,
+        icon: item.icon || col?.admin?.icon || "Folder",
+        group: groupName,
+        order: item.order ?? col?.admin?.order ?? 100,
+        views: combinedViews,
+        badge: item.badge,
+        access: item.access || col?.access?.read
+      });
+      continue;
+    }
+    if (item.global) {
+      const gl = globalsBySlug.get(item.global);
+      registerItem(groupName, {
+        id: item.slug || `global_${item.global}`,
+        type: "global",
+        slug: item.slug || item.global,
+        global: item.global,
+        label: item.label || gl?.label || item.global,
+        icon: item.icon || "Settings",
+        group: groupName,
+        order: item.order ?? 100,
+        views: [],
+        badge: item.badge,
+        access: item.access
+      });
+      continue;
+    }
+    if (item.href) {
+      registerItem(groupName, {
+        id: `link_${item.slug || item.href}`,
+        type: "link",
+        slug: item.slug || "link",
+        label: item.label || "Link",
+        href: item.href,
+        icon: item.icon || "ExternalLink",
+        group: groupName,
+        order: item.order ?? 100,
+        views: [],
+        badge: item.badge,
+        access: item.access
+      });
+      continue;
+    }
+    const workspaceSlug = item.slug || "workspace";
+    registerItem(groupName, {
+      id: `workspace_${workspaceSlug}`,
+      type: "workspace",
+      slug: workspaceSlug,
+      label: item.label || workspaceSlug,
+      icon: item.icon || "Briefcase",
+      group: groupName,
+      order: item.order ?? 100,
+      views: item.views || [],
+      badge: item.badge,
+      access: item.access
+    });
+  }
+  for (const col of collections) {
+    if (mentionedCollections.has(col.slug)) continue;
+    if (col.admin?.hidden) continue;
+    const groupProp = col.admin?.group;
+    const { name: groupName, meta: groupMeta } = resolveGroupMeta(groupProp, "Collections");
+    if (groupMeta) {
+      groupMetadataMap.set(groupName, { ...groupMetadataMap.get(groupName) || {}, ...groupMeta });
+    }
+    const combinedViews = [
+      ...col.views || [],
+      ...injectedViewsByCollection.get(col.slug) || []
+    ];
+    registerItem(groupName, {
+      id: `collection_${col.slug}`,
+      type: "collection",
+      slug: col.slug,
+      collection: col.slug,
+      label: col.labels?.plural || col.slug,
+      icon: col.admin?.icon || "Folder",
+      group: groupName,
+      order: col?.admin?.order ?? 100,
+      views: combinedViews,
+      access: col.access?.read
+    });
+  }
+  for (const gl of globals) {
+    if (mentionedGlobals.has(gl.slug)) continue;
+    const groupName = "Configuration";
+    registerItem(groupName, {
+      id: `global_${gl.slug}`,
+      type: "global",
+      slug: gl.slug,
+      global: gl.slug,
+      label: gl.label || gl.slug,
+      icon: "Settings",
+      group: groupName,
+      order: 100,
+      views: []
+    });
+  }
+  const sortAndSpliceItems = (items) => {
+    const sorted = [...items].sort((a, b) => a.order - b.order);
+    const explicitMap = /* @__PURE__ */ new Map();
+    for (const opt of explicitNav) {
+      if (opt.slug) explicitMap.set(opt.slug, opt);
+      if (opt.collection) explicitMap.set(opt.collection, opt);
+      if (opt.global) explicitMap.set(opt.global, opt);
+    }
+    for (const opt of explicitNav) {
+      const itemKey = opt.slug || opt.collection || opt.global;
+      if (!itemKey) continue;
+      if (opt.after) {
+        const itemIdx = sorted.findIndex((i) => i.slug === itemKey);
+        const targetIdx = sorted.findIndex((i) => i.slug === opt.after);
+        if (itemIdx !== -1 && targetIdx !== -1 && itemIdx !== targetIdx) {
+          const [moved] = sorted.splice(itemIdx, 1);
+          const newTargetIdx = sorted.findIndex((i) => i.slug === opt.after);
+          sorted.splice(newTargetIdx + 1, 0, moved);
+        }
+      } else if (opt.before) {
+        const itemIdx = sorted.findIndex((i) => i.slug === itemKey);
+        const targetIdx = sorted.findIndex((i) => i.slug === opt.before);
+        if (itemIdx !== -1 && targetIdx !== -1 && itemIdx !== targetIdx) {
+          const [moved] = sorted.splice(itemIdx, 1);
+          const newTargetIdx = sorted.findIndex((i) => i.slug === opt.before);
+          sorted.splice(newTargetIdx, 0, moved);
+        }
+      } else if (opt.position === "first") {
+        const itemIdx = sorted.findIndex((i) => i.slug === itemKey);
+        if (itemIdx > 0) {
+          const [moved] = sorted.splice(itemIdx, 1);
+          sorted.unshift(moved);
+        }
+      } else if (opt.position === "last") {
+        const itemIdx = sorted.findIndex((i) => i.slug === itemKey);
+        if (itemIdx !== -1 && itemIdx < sorted.length - 1) {
+          const [moved] = sorted.splice(itemIdx, 1);
+          sorted.push(moved);
+        }
+      }
+    }
+    return sorted;
+  };
+  const compiledGroups = [];
+  for (const [groupName, rawItems] of itemsByGroup.entries()) {
+    const meta = groupMetadataMap.get(groupName);
+    const sortedItems = sortAndSpliceItems(rawItems);
+    compiledGroups.push({
+      id: `group_${groupName.toLowerCase().replace(/\s+/g, "_")}`,
+      name: groupName,
+      slug: meta?.slug || groupName.toLowerCase().replace(/\s+/g, "-"),
+      icon: meta?.icon,
+      defaultExpanded: meta?.defaultExpanded ?? true,
+      order: meta?.order ?? 100,
+      items: sortedItems
+    });
+  }
+  compiledGroups.sort((a, b) => a.order - b.order);
+  return {
+    groups: compiledGroups,
+    ungrouped: sortAndSpliceItems(ungroupedItems)
+  };
+}
+function pruneNavigationForUser(tree, user) {
+  const userRoles = /* @__PURE__ */ new Set();
+  if (user?.role) userRoles.add(user.role);
+  if (Array.isArray(user?.roles)) {
+    for (const r of user.roles) userRoles.add(r);
+  }
+  const isAllowed = (item) => {
+    if (!item.access) return true;
+    if (Array.isArray(item.access)) {
+      if (item.access.length === 0) return true;
+      return item.access.some((role) => userRoles.has(role));
+    }
+    return true;
+  };
+  const prunedGroups = [];
+  for (const group of tree.groups) {
+    const visibleItems = group.items.filter(isAllowed);
+    if (visibleItems.length > 0) {
+      prunedGroups.push({
+        ...group,
+        items: visibleItems
+      });
+    }
+  }
+  return {
+    groups: prunedGroups,
+    ungrouped: tree.ungrouped.filter(isAllowed)
+  };
+}
+
 // src/index.ts
 import { z } from "zod";
 function defineCollection(config) {
@@ -6432,9 +7151,14 @@ export {
   AI_CHUNKS_COLLECTION,
   AI_MESSAGES_COLLECTION,
   AI_THREADS_COLLECTION,
+  BASE62_ALPHABET,
   BUILTIN_JEXL_HELPERS,
+  CROCKFORD_BASE32,
+  CURRENT_NAV_PREFERENCES_VERSION,
   ConfigValidationError,
   ConflictError,
+  DEFAULT_USER_NAV_PREFERENCES,
+  DuplicateKeyError,
   DyrectedAIError,
   DyrectedError,
   FieldConditionBuilder,
@@ -6442,9 +7166,11 @@ export {
   LIFECYCLE_EVENTS_COLLECTION,
   LIFECYCLE_EVENT_NAMES,
   MatchBuilder,
+  NANOID_ALPHABET,
   NON_NEGOTIABLE_CREDENTIAL_FIELDS,
   NotFoundError,
   PII_REGEX_PATTERNS,
+  RESERVED_NAVIGATION_SLUGS,
   ValidationError,
   WORKFLOW_HISTORY_COLLECTION,
   abs,
@@ -6455,6 +7181,7 @@ export {
   assertValidDeclarativeHookExpression,
   assertValidDeclarativeHookResult,
   assertValidDeclarativeHooksInConfig,
+  assertValidNavigationSlugs,
   assertValidPreviewUrlsInConfig,
   availableWorkflowTransitions,
   buildSqlOrderBy,
@@ -6469,6 +7196,7 @@ export {
   collectDeclarativeHookValidationIssues,
   collectPreviewUrlValidationIssues,
   compact,
+  compileNavigation,
   count,
   createLifecycleEvent,
   createWorkflowDocument,
@@ -6509,6 +7237,7 @@ export {
   defineTimeField,
   defineUrlField,
   defineView,
+  defineWorkspace,
   diffDays,
   dispatchLifecycleEvent,
   dispatchPendingLifecycleEvents,
@@ -6537,6 +7266,8 @@ export {
   formatDate,
   formatJexlValue,
   generateDefaultDetailSchema,
+  generateDocumentId,
+  generateId,
   generateOpenApi,
   get,
   getAdminAuthCollection,
@@ -6563,6 +7294,7 @@ export {
   materializeWorkflowDocument,
   max,
   min,
+  nanoid,
   normalizeConfig,
   normalizeDetailItem,
   now,
@@ -6571,13 +7303,17 @@ export {
   parseSort,
   parseSqlWhere,
   pow,
+  prefixedId,
+  pruneNavigationForUser,
   publishedStateName,
   publishingWorkflow,
   readingTime,
+  reconcileNavigation,
   registerJexlHelpers,
   replace,
   resolveAdminAuthCollection,
   resolveAuthorizedSiteId,
+  resolvePrefix,
   round,
   runCollectionHooks,
   sanitizeDocForAI,
@@ -6591,8 +7327,10 @@ export {
   transitionWorkflow,
   trim,
   truncate,
+  ulid,
   unique,
   upper,
+  uuid,
   validateAdminConditionExpression,
   validateDeclarativeAccessExpression,
   validateDeclarativeHookExpression,