@dyrected/core 2.16.0 → 2.18.0

package/dist/index.js

@@ -1845,12 +1845,317 @@ 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";
 
 // src/auth/sessions.ts
 var AUTH_SESSIONS_COLLECTION = "__auth_sessions";
 
+// src/tasks.ts
+var TASK_LOCKS_COLLECTION = "__task_locks";
+var TASK_LOCKS_COLLECTION_CONFIG = {
+  slug: TASK_LOCKS_COLLECTION,
+  labels: { singular: "Task lock", plural: "Task locks" },
+  fields: [
+    { name: "name", type: "text", required: true },
+    // Numeric and promoted so the lock compare-and-set is a real column comparison.
+    { name: "lockedUntil", type: "number", required: true, promoted: true },
+    { name: "lockedBy", type: "text" },
+    { name: "lastScheduledFor", type: "date" },
+    { name: "lastStartedAt", type: "date" },
+    { name: "lastFinishedAt", type: "date" },
+    { name: "lastStatus", type: "text" },
+    { name: "lastError", type: "textarea" }
+  ],
+  access: {
+    read: ({ user }) => !!user?.roles?.includes("admin"),
+    create: () => false,
+    update: () => false,
+    delete: () => false
+  },
+  admin: { hidden: true }
+};
+var DEFAULT_LOCK_TIMEOUT_SECONDS = 300;
+var DEFAULT_TICK_MS = 3e4;
+var MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+var DAY_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+function parseCronField(raw, min2, max2, names, nameOffset, label) {
+  const values = /* @__PURE__ */ new Set();
+  const toNumber = (token) => {
+    const named = names?.indexOf(token.toLowerCase());
+    if (named !== void 0 && named >= 0) return named + nameOffset;
+    if (!/^\d+$/.test(token)) throw new Error(`Invalid cron ${label} "${token}".`);
+    return Number(token);
+  };
+  for (const part of raw.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === void 0 ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) throw new Error(`Invalid cron ${label} step "${part}".`);
+    let start;
+    let end;
+    if (rangePart === "*") {
+      start = min2;
+      end = max2;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-");
+      start = toNumber(a);
+      end = toNumber(b);
+    } else {
+      start = toNumber(rangePart);
+      end = stepPart === void 0 ? start : max2;
+    }
+    if (start < min2 || end > max2 || start > end) {
+      throw new Error(`Cron ${label} "${part}" is out of range (${min2}-${max2}).`);
+    }
+    for (let v = start; v <= end; v += step) values.add(v);
+  }
+  return values;
+}
+function parseCron(expression) {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`Cron expression "${expression}" must have 5 fields (minute hour day-of-month month day-of-week).`);
+  }
+  const [min2, hour, dom, mon, dow] = fields;
+  const daysOfWeek = parseCronField(dow, 0, 7, DAY_NAMES, 0, "day-of-week");
+  if (daysOfWeek.has(7)) daysOfWeek.add(0);
+  daysOfWeek.delete(7);
+  return {
+    minutes: parseCronField(min2, 0, 59, void 0, 0, "minute"),
+    hours: parseCronField(hour, 0, 23, void 0, 0, "hour"),
+    daysOfMonth: parseCronField(dom, 1, 31, void 0, 0, "day-of-month"),
+    months: parseCronField(mon, 1, 12, MONTH_NAMES, 1, "month"),
+    daysOfWeek,
+    dayFieldsBothRestricted: dom !== "*" && dow !== "*"
+  };
+}
+function dayMatches(schedule, date) {
+  const domOk = schedule.daysOfMonth.has(date.getUTCDate());
+  const dowOk = schedule.daysOfWeek.has(date.getUTCDay());
+  return schedule.dayFieldsBothRestricted ? domOk || dowOk : domOk && dowOk;
+}
+function nextCronRun(expression, after) {
+  const schedule = typeof expression === "string" ? parseCron(expression) : expression;
+  const cursor = new Date(after.getTime());
+  cursor.setUTCSeconds(0, 0);
+  cursor.setUTCMinutes(cursor.getUTCMinutes() + 1);
+  const limit = after.getTime() + 5 * 366 * 24 * 60 * 60 * 1e3;
+  while (cursor.getTime() <= limit) {
+    if (!schedule.months.has(cursor.getUTCMonth() + 1)) {
+      cursor.setUTCMonth(cursor.getUTCMonth() + 1, 1);
+      cursor.setUTCHours(0, 0, 0, 0);
+      continue;
+    }
+    if (!dayMatches(schedule, cursor)) {
+      cursor.setUTCDate(cursor.getUTCDate() + 1);
+      cursor.setUTCHours(0, 0, 0, 0);
+      continue;
+    }
+    if (!schedule.hours.has(cursor.getUTCHours())) {
+      cursor.setUTCHours(cursor.getUTCHours() + 1, 0, 0, 0);
+      continue;
+    }
+    if (!schedule.minutes.has(cursor.getUTCMinutes())) {
+      cursor.setUTCMinutes(cursor.getUTCMinutes() + 1, 0, 0);
+      continue;
+    }
+    return cursor;
+  }
+  throw new Error(`Cron expression "${typeof expression === "string" ? expression : "schedule"}" never matches.`);
+}
+function defineTask(task) {
+  if (!task.name || !task.name.trim()) throw new Error("A task needs a non-empty name.");
+  if (task.cron !== void 0) parseCron(task.cron);
+  if (task.lockTimeout !== void 0 && !(task.lockTimeout > 0)) {
+    throw new Error(`Task "${task.name}" lockTimeout must be a positive number of seconds.`);
+  }
+  return task;
+}
+function resolveLogger(config, taskName) {
+  const base = config.logger;
+  if (base && typeof base.child === "function") return base.child({ component: "tasks", task: taskName });
+  const prefix = `[dyrected/tasks] ${taskName}`;
+  return {
+    info: (obj, msg) => console.info(prefix, msg ?? "", obj),
+    warn: (obj, msg) => console.warn(prefix, msg ?? "", obj),
+    error: (obj, msg) => console.error(prefix, msg ?? "", obj)
+  };
+}
+function floorToMinute(date) {
+  const d = new Date(date.getTime());
+  d.setUTCSeconds(0, 0);
+  return d;
+}
+function createTaskRunner(config) {
+  const db = config.db;
+  if (!db) throw new Error("createTaskRunner requires config.db.");
+  const tasks = /* @__PURE__ */ new Map();
+  for (const task of config.tasks ?? []) {
+    if (tasks.has(task.name)) throw new Error(`Duplicate task name "${task.name}".`);
+    tasks.set(task.name, { ...task, schedule: task.cron ? parseCron(task.cron) : void 0 });
+  }
+  const instanceId = globalThis.crypto?.randomUUID?.() ?? `inst_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+  let timer;
+  let inFlight = Promise.resolve();
+  let ticking = false;
+  let ready;
+  function ensureReady() {
+    ready ??= Promise.resolve(db.sync?.([TASK_LOCKS_COLLECTION_CONFIG], [])).then(() => void 0);
+    ready.catch(() => {
+      ready = void 0;
+    });
+    return ready;
+  }
+  async function ensureLockRow(name, now2) {
+    await ensureReady();
+    const existing = await db.findOne({ collection: TASK_LOCKS_COLLECTION, id: name });
+    if (existing) return existing;
+    try {
+      return await db.create({
+        collection: TASK_LOCKS_COLLECTION,
+        data: {
+          id: name,
+          name,
+          lockedUntil: 0,
+          lockedBy: null,
+          lastScheduledFor: floorToMinute(now2).toISOString(),
+          lastStartedAt: null,
+          lastFinishedAt: null,
+          lastStatus: null,
+          lastError: null
+        }
+      });
+    } catch (error) {
+      const created = await db.findOne({ collection: TASK_LOCKS_COLLECTION, id: name });
+      if (created) return created;
+      throw error;
+    }
+  }
+  async function execute(task, row, scheduledFor) {
+    const started = Date.now();
+    const lockMs = (task.lockTimeout ?? DEFAULT_LOCK_TIMEOUT_SECONDS) * 1e3;
+    const token = `${instanceId}:${started}`;
+    const where = {
+      id: { equals: task.name },
+      lockedUntil: { less_than: started }
+    };
+    if (scheduledFor) where.lastScheduledFor = { equals: row.lastScheduledFor };
+    const claimed = await db.update({
+      collection: TASK_LOCKS_COLLECTION,
+      where,
+      data: {
+        lockedUntil: started + lockMs,
+        lockedBy: token,
+        lastStartedAt: new Date(started).toISOString(),
+        ...scheduledFor ? { lastScheduledFor: scheduledFor.toISOString() } : {}
+      }
+    });
+    if (claimed.affectedRows !== 1) {
+      return { name: task.name, status: "skipped", reason: "locked", durationMs: Date.now() - started };
+    }
+    const logger = resolveLogger(config, task.name);
+    const controller = new AbortController();
+    let timeout;
+    let status = "completed";
+    let errorMessage;
+    try {
+      await Promise.race([
+        Promise.resolve(task.run({ db, logger, signal: controller.signal, scheduledFor })),
+        new Promise((_, reject) => {
+          timeout = setTimeout(() => {
+            reject(new Error(`Task exceeded its lockTimeout of ${lockMs / 1e3}s.`));
+            controller.abort();
+          }, lockMs);
+        })
+      ]);
+    } catch (error) {
+      status = "failed";
+      errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error({ err: error }, "Task failed");
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+    try {
+      await db.update({
+        collection: TASK_LOCKS_COLLECTION,
+        where: { id: { equals: task.name }, lockedBy: { equals: token } },
+        data: {
+          lockedUntil: 0,
+          lockedBy: null,
+          lastFinishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          lastStatus: status,
+          lastError: errorMessage ?? null
+        }
+      });
+    } catch (error) {
+      logger.warn({ err: error }, "Could not release task lock; it will expire on its own");
+    }
+    return { name: task.name, status, error: errorMessage, durationMs: Date.now() - started };
+  }
+  function track(work) {
+    inFlight = inFlight.then(() => work).catch(() => void 0);
+    return work;
+  }
+  const runner = {
+    async runTask(name) {
+      const task = tasks.get(name);
+      if (!task) throw new Error(`Unknown task "${name}".`);
+      const row = await ensureLockRow(name, /* @__PURE__ */ new Date());
+      return track(execute(task, row, void 0));
+    },
+    async runDue(now2 = /* @__PURE__ */ new Date()) {
+      const results = [];
+      for (const task of tasks.values()) {
+        if (!task.schedule) continue;
+        const row = await ensureLockRow(task.name, now2);
+        const reference = new Date(String(row.lastScheduledFor));
+        const due = Number.isNaN(reference.getTime()) ? true : nextCronRun(task.schedule, reference).getTime() <= now2.getTime();
+        if (!due) {
+          results.push({ name: task.name, status: "skipped", reason: "not-due", durationMs: 0 });
+          continue;
+        }
+        results.push(await track(execute(task, row, floorToMinute(now2))));
+      }
+      return results;
+    },
+    start(options) {
+      if (timer) return;
+      const intervalMs = options?.intervalMs ?? DEFAULT_TICK_MS;
+      const tick = () => {
+        if (ticking) return;
+        ticking = true;
+        runner.runDue().catch((error) => resolveLogger(config, "runner").error({ err: error }, "Task tick failed")).finally(() => {
+          ticking = false;
+        });
+      };
+      timer = setInterval(tick, intervalMs);
+      timer.unref?.();
+      setTimeout(tick, 0);
+    },
+    async stop() {
+      if (timer) clearInterval(timer);
+      timer = void 0;
+      await inFlight;
+    }
+  };
+  return runner;
+}
+
 // src/workflows.ts
 var WORKFLOW_HISTORY_COLLECTION = "__workflow_history";
 var LIFECYCLE_EVENTS_COLLECTION = "__lifecycle_events";
@@ -2066,7 +2371,7 @@ async function dispatchPendingLifecycleEvents(config, limit = 50) {
   return due.length;
 }
 async function saveWorkflowDraft(args) {
-  const { config, collection, id, originalDoc, data, user } = args;
+  const { config, collection, id, originalDoc, data, user, beforeCommit } = args;
   const db = config.db;
   const workflow = collection.workflow;
   if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
@@ -2100,13 +2405,14 @@ async function saveWorkflowDraft(args) {
     }
     const updated = await tx.update({ collection: collection.slug, id, data: updateData });
     await persistEvent(tx, event);
+    await beforeCommit?.(tx, updated);
     return updated;
   });
   void dispatchLifecycleEvent(config, event);
   return { doc, event };
 }
 async function createWorkflowDocument(args) {
-  const { config, collection, data, user } = args;
+  const { config, collection, data, user, beforeCommit } = args;
   const db = config.db;
   if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
   let event;
@@ -2120,13 +2426,14 @@ async function createWorkflowDocument(args) {
       payload: { revision: 1, previousRevision: null }
     });
     await persistEvent(tx, event);
+    await beforeCommit?.(tx, created);
     return created;
   });
   void dispatchLifecycleEvent(config, event);
   return { doc, event };
 }
 async function transitionWorkflow(args) {
-  const { config, collection, id, transitionName, expectedRevision, comment, user, req } = args;
+  const { config, collection, id, transitionName, expectedRevision, comment, input, user, req } = args;
   const db = config.db;
   const workflow = collection.workflow;
   if (!db.transaction) throw new Error(`The configured database adapter does not support workflow transactions.`);
@@ -2152,7 +2459,7 @@ async function transitionWorkflow(args) {
   if (transition.requireComment && !comment?.trim()) {
     throw Object.assign(new Error(`A comment is required for "${transition.label}".`), { statusCode: 400 });
   }
-  const hookContext = { transition, from: meta.state, to: transition.to, doc: original, user, comment, req, db };
+  const hookContext = { transition, from: meta.state, to: transition.to, doc: original, user, comment, input, req, db };
   for (const hook of workflow.hooks?.beforeTransition ?? []) await hook(hookContext);
   const events = [
     createLifecycleEvent({
@@ -2206,6 +2513,19 @@ async function transitionWorkflow(args) {
     if (targetState.published) data.__published = working;
     if (transition.unpublish) data.__published = null;
     const next = await tx.update({ collection: collection.slug, id, data });
+    if (transition.onTransition) {
+      await transition.onTransition({
+        transition,
+        from: lockedMeta.state,
+        to: transition.to,
+        doc: locked,
+        input,
+        comment,
+        user,
+        req,
+        tx
+      });
+    }
     await tx.create({
       collection: WORKFLOW_HISTORY_COLLECTION,
       data: {
@@ -3642,6 +3962,7 @@ function normalizeConfig(config) {
   const globals = schemaAwareConfig?.globals || [];
   const needsAudit = collections.some((col) => col.audit);
   const needsWorkflow = collections.some((col) => col.workflow || col.drafts);
+  const needsTasks = (config.tasks?.length ?? 0) > 0;
   const needsAuthSessions = collections.some((col) => !!col.auth);
   const adminAuthCollectionSlug = getAdminAuthCollection({
     collections,
@@ -3721,7 +4042,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,
@@ -3848,6 +4195,9 @@ function normalizeConfig(config) {
   if (needsWorkflow && !normalizedCollections.some((col) => col.slug === LIFECYCLE_EVENTS_COLLECTION)) {
     systemCollections.push(LIFECYCLE_EVENTS_COLLECTION_CONFIG);
   }
+  if (needsTasks && !normalizedCollections.some((col) => col.slug === TASK_LOCKS_COLLECTION)) {
+    systemCollections.push(TASK_LOCKS_COLLECTION_CONFIG);
+  }
   if (needsAuthSessions && !normalizedCollections.some((col) => col.slug === AUTH_SESSIONS_COLLECTION)) {
     systemCollections.push(AUTH_SESSIONS_COLLECTION_CONFIG);
   }
@@ -3932,7 +4282,11 @@ function parseSqlWhere(where, getJsonField, placeholder = "?", likeOperator = pl
         params.push("");
         return `(${c})::text = ${next()}`;
       }
-      params.push(typeof value === "boolean" && isJsonExtract ? String(value) : value);
+      if (typeof value === "boolean") {
+        params.push(placeholder === "?" ? value ? 1 : 0 : isJsonExtract ? String(value) : value);
+      } else {
+        params.push(value);
+      }
       return `${c} = ${next()}`;
     }
     const entries = Object.entries(value);
@@ -4132,6 +4486,38 @@ function parseMongoWhere(where) {
   }
   return buildClause(where);
 }
+function coerceBooleanWhere(where, fields) {
+  const booleanFields = new Set(
+    (fields ?? []).filter((f) => f.type === "boolean" && f.name).map((f) => f.name)
+  );
+  if (booleanFields.size === 0) return where;
+  const toBool = (v) => v === "true" ? true : v === "false" ? false : v;
+  const walk = (node) => {
+    if (Array.isArray(node)) return node.map(walk);
+    if (!node || typeof node !== "object") return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key.toUpperCase() === "AND" || key.toUpperCase() === "OR") {
+        out[key] = walk(value);
+      } else if (booleanFields.has(key)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          out[key] = Object.fromEntries(
+            Object.entries(value).map(([op, operand]) => [
+              op,
+              Array.isArray(operand) ? operand.map(toBool) : toBool(operand)
+            ])
+          );
+        } else {
+          out[key] = toBool(value);
+        }
+      } else {
+        out[key] = value;
+      }
+    }
+    return out;
+  };
+  return walk(where);
+}
 
 // src/utils/parse-sort.ts
 var SORT_FIELD_PATTERN = /^([A-Za-z_][A-Za-z0-9_]*)(?:\s+(ASC|DESC))?$/i;
@@ -4413,7 +4799,12 @@ function generateOpenApi(config) {
           type: "object",
           properties: {
             expectedRevision: { type: "integer", minimum: 1 },
-            comment: { type: "string" }
+            comment: { type: "string" },
+            input: {
+              type: "object",
+              additionalProperties: true,
+              description: "Extra data passed to the transition's onTransition handler."
+            }
           }
         },
         WorkflowHistoryEntry: {
@@ -5576,6 +5967,9 @@ function fieldToSchema(field) {
     case "number":
       schema = { type: "number" };
       break;
+    case "money":
+      schema = { type: "integer", description: "Amount in minor units (for example kobo or cents)." };
+      break;
     case "boolean":
       schema = { type: "boolean" };
       break;
@@ -6528,6 +6922,555 @@ function sanitizeDocForAI(options) {
   return result;
 }
 
+// src/utils/index-name.ts
+import { createHash } from "crypto";
+var MAX_INDEX_NAME_LENGTH = 60;
+function resolveIndexName(prefix, table, fields) {
+  const full = `${prefix}_${table}_${fields.join("_")}`;
+  if (full.length <= MAX_INDEX_NAME_LENGTH) return full;
+  const hash = createHash("sha1").update(full).digest("hex").slice(0, 10);
+  const tail = (fields[fields.length - 1] ?? "").slice(0, 30);
+  return `${prefix}_${hash}_${tail}`;
+}
+
+// src/utils/group-key.ts
+var UNASSIGNED_GROUP_KEY = "__unassigned__";
+var MYSQL_DATETIME = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(\.\d+)?$/;
+function normalizeGroupKey(raw, fieldType) {
+  if (raw === null || raw === void 0) return UNASSIGNED_GROUP_KEY;
+  if (fieldType === "boolean") {
+    if (raw === true || raw === 1 || raw === "1" || raw === "true" || raw === "t") return "true";
+    if (raw === false || raw === 0 || raw === "0" || raw === "false" || raw === "f") return "false";
+  }
+  if ((fieldType === "number" || fieldType === "money") && raw !== "" && !Number.isNaN(Number(raw))) {
+    return String(Number(raw));
+  }
+  if (fieldType === "date" || fieldType === "datetime") {
+    if (raw instanceof Date) return Number.isNaN(raw.getTime()) ? String(raw) : raw.toISOString();
+    if (typeof raw === "string" && MYSQL_DATETIME.test(raw)) return `${raw.replace(" ", "T")}Z`;
+  }
+  return String(raw);
+}
+
+// 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) {
@@ -6552,6 +7495,7 @@ var defineTextField = createFieldDefiner("text");
 var defineTextareaField = createFieldDefiner("textarea");
 var defineRichTextField = createFieldDefiner("richText");
 var defineNumberField = createFieldDefiner("number");
+var defineMoneyField = createFieldDefiner("money");
 var defineBooleanField = createFieldDefiner("boolean");
 var defineDateField = createFieldDefiner("date");
 var defineDateTimeField = createFieldDefiner("datetime");
@@ -6594,8 +7538,10 @@ export {
   BASE62_ALPHABET,
   BUILTIN_JEXL_HELPERS,
   CROCKFORD_BASE32,
+  CURRENT_NAV_PREFERENCES_VERSION,
   ConfigValidationError,
   ConflictError,
+  DEFAULT_USER_NAV_PREFERENCES,
   DuplicateKeyError,
   DyrectedAIError,
   DyrectedError,
@@ -6608,6 +7554,10 @@ export {
   NON_NEGOTIABLE_CREDENTIAL_FIELDS,
   NotFoundError,
   PII_REGEX_PATTERNS,
+  RESERVED_NAVIGATION_SLUGS,
+  TASK_LOCKS_COLLECTION,
+  TASK_LOCKS_COLLECTION_CONFIG,
+  UNASSIGNED_GROUP_KEY,
   ValidationError,
   WORKFLOW_HISTORY_COLLECTION,
   abs,
@@ -6618,6 +7568,7 @@ export {
   assertValidDeclarativeHookExpression,
   assertValidDeclarativeHookResult,
   assertValidDeclarativeHooksInConfig,
+  assertValidNavigationSlugs,
   assertValidPreviewUrlsInConfig,
   availableWorkflowTransitions,
   buildSqlOrderBy,
@@ -6626,14 +7577,17 @@ export {
   ceil,
   clamp,
   coalesce,
+  coerceBooleanWhere,
   collectAdminConditionValidationIssues,
   collectConfigDiagnostics,
   collectDeclarativeAccessValidationIssues,
   collectDeclarativeHookValidationIssues,
   collectPreviewUrlValidationIssues,
   compact,
+  compileNavigation,
   count,
   createLifecycleEvent,
+  createTaskRunner,
   createWorkflowDocument,
   defaultValue,
   defineAction,
@@ -6656,6 +7610,7 @@ export {
   defineJoinField,
   defineJsonField,
   defineKanbanView,
+  defineMoneyField,
   defineMultiSelectField,
   defineNumberField,
   defineObjectField,
@@ -6667,11 +7622,13 @@ export {
   defineSelectField,
   defineTab,
   defineTableView,
+  defineTask,
   defineTextField,
   defineTextareaField,
   defineTimeField,
   defineUrlField,
   defineView,
+  defineWorkspace,
   diffDays,
   dispatchLifecycleEvent,
   dispatchPendingLifecycleEvents,
@@ -6729,22 +7686,28 @@ export {
   max,
   min,
   nanoid,
+  nextCronRun,
   normalizeConfig,
   normalizeDetailItem,
+  normalizeGroupKey,
   now,
   numericFieldNames,
+  parseCron,
   parseMongoWhere,
   parseSort,
   parseSqlWhere,
   pow,
   prefixedId,
+  pruneNavigationForUser,
   publishedStateName,
   publishingWorkflow,
   readingTime,
+  reconcileNavigation,
   registerJexlHelpers,
   replace,
   resolveAdminAuthCollection,
   resolveAuthorizedSiteId,
+  resolveIndexName,
   resolvePrefix,
   round,
   runCollectionHooks,