@momentumcms/core 0.1.10 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.3.0 (2026-02-20)
+
+### 🚀 Features
+
+- implement Payload-style migration CLI workflow with clone-test-apply safety ([#35](https://github.com/DonaldMurillo/momentum-cms/pull/35))
+- add named tabs support with nested data grouping and UI improvements ([#30](https://github.com/DonaldMurillo/momentum-cms/pull/30))
+
+### 🩹 Fixes
+
+- fix nav highlighting and resolve pre-existing E2E test failures ([#34](https://github.com/DonaldMurillo/momentum-cms/pull/34))
+- add auth guard and MIME validation to PATCH upload route; fix pagination with client-side filtering ([#32](https://github.com/DonaldMurillo/momentum-cms/pull/32))
+
+### ❤️ Thank You
+
+- Claude Haiku 4.5
+- Claude Opus 4.6
+- Donald Murillo @DonaldMurillo
+
+## 0.2.0 (2026-02-17)
+
+### 🚀 Features
+
+- add named tabs support with nested data grouping and tab UI improvements ([63ab63e](https://github.com/DonaldMurillo/momentum-cms/commit/63ab63e))
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Donald Murillo @DonaldMurillo
+
 ## 0.1.10 (2026-02-17)
 
 ### 🩹 Fixes

package/generators/generator.cjs

@@ -36,12 +36,26 @@ var import_node_path = require("node:path");
 var import_node_url = require("node:url");
 
 // libs/core/src/lib/fields/field.types.ts
+function isNamedTab(tab) {
+  return typeof tab.name === "string" && tab.name.length > 0;
+}
 function flattenDataFields(fields) {
   const result = [];
   for (const field of fields) {
     if (field.type === "tabs") {
       for (const tab of field.tabs) {
-        result.push(...flattenDataFields(tab.fields));
+        if (isNamedTab(tab)) {
+          const syntheticGroup = {
+            name: tab.name,
+            type: "group",
+            label: tab.label,
+            description: tab.description,
+            fields: tab.fields
+          };
+          result.push(syntheticGroup);
+        } else {
+          result.push(...flattenDataFields(tab.fields));
+        }
       }
     } else if (field.type === "collapsible" || field.type === "row") {
       result.push(...flattenDataFields(field.fields));
@@ -262,11 +276,7 @@ function generateTypes(config) {
     const hasTimestamps = collection.timestamps !== false;
     for (const field of dataFields) {
       if (field.type === "blocks") {
-        const blockResult = generateBlockTypes(
-          collection.slug,
-          field.name,
-          field
-        );
+        const blockResult = generateBlockTypes(collection.slug, field.name, field);
         blockDeclarations.push(blockResult.declarations);
       }
     }
@@ -280,11 +290,7 @@ function generateTypes(config) {
       const optional = field.required ? "" : "?";
       const propName = needsQuoting2(field.name) ? safeQuote(field.name) : field.name;
       if (field.type === "blocks") {
-        const blockResult = generateBlockTypes(
-          collection.slug,
-          field.name,
-          field
-        );
+        const blockResult = generateBlockTypes(collection.slug, field.name, field);
         lines.push(`  ${propName}${optional}: ${blockResult.unionTypeName}[];`);
       } else {
         const tsType = fieldTypeToTS(field);
@@ -386,6 +392,25 @@ var FIELD_ADMIN_STRIP_KEYS = /* @__PURE__ */ new Set(["condition"]);
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function previewFunctionToTemplate(fn, fields) {
+  try {
+    const sentinel = "__MCMS_FIELD_";
+    const mockDoc = {};
+    for (const field of fields) {
+      mockDoc[field.name] = `${sentinel}${field.name}__`;
+    }
+    const result = fn(mockDoc);
+    if (typeof result !== "string")
+      return true;
+    const template = result.replace(
+      new RegExp(`${sentinel}(\\w+)__`, "g"),
+      (_match, fieldName) => `{${fieldName}}`
+    );
+    return template;
+  } catch {
+    return true;
+  }
+}
 function serializeValue(value, indent = "	") {
   if (value === null)
     return "null";
@@ -554,6 +579,9 @@ function serializeTabsArray(tabs, indent) {
     return "[]";
   const items = tabs.map((tab) => {
     const parts = [];
+    if (tab.name) {
+      parts.push(`${indent}		name: ${JSON.stringify(tab.name)}`);
+    }
     parts.push(`${indent}		label: ${JSON.stringify(tab.label)}`);
     if (tab.description) {
       parts.push(`${indent}		description: ${JSON.stringify(tab.description)}`);
@@ -575,9 +603,13 @@ function serializeCollection(collection, indent = "	") {
   }
   parts.push(`${indent}	fields: ${serializeFieldsArray(collection.fields, indent + "	")}`);
   if (collection.admin) {
-    const adminEntries = Object.entries(collection.admin).filter(
-      ([, v]) => v !== void 0 && typeof v !== "function"
-    );
+    const adminEntries = Object.entries(collection.admin).filter(([, v]) => v !== void 0).map(([k, v]) => {
+      if (k === "preview" && typeof v === "function") {
+        const fn = v;
+        return [k, previewFunctionToTemplate(fn, collection.fields)];
+      }
+      return [k, v];
+    }).filter(([, v]) => typeof v !== "function");
     if (adminEntries.length > 0) {
       const adminObj = Object.fromEntries(adminEntries);
       parts.push(`${indent}	admin: ${serializeValue(adminObj, indent + "	")}`);
@@ -601,6 +633,9 @@ function serializeCollection(collection, indent = "	") {
   if (collection.defaultSort) {
     parts.push(`${indent}	defaultSort: ${JSON.stringify(collection.defaultSort)}`);
   }
+  if (collection.upload !== void 0) {
+    parts.push(`${indent}	upload: ${serializeValue(collection.upload, indent + "	")}`);
+  }
   return `{
 ${parts.join(",\n")},
 ${indent}}`;
@@ -730,6 +765,15 @@ function parseArgs(args) {
   }
   return { configPath, typesOutputPath, configOutputPath, watch: watchMode };
 }
+function formatWithPrettier(...filePaths) {
+  try {
+    (0, import_node_child_process.execFileSync)("npx", ["prettier", "--write", ...filePaths], {
+      stdio: "pipe"
+    });
+  } catch {
+    console.warn("prettier not available \u2014 skipping formatting of generated files");
+  }
+}
 async function runGenerator(options) {
   const configPath = (0, import_node_path.resolve)(options.configPath);
   const typesOutputPath = (0, import_node_path.resolve)(options.typesOutputPath);
@@ -749,6 +793,7 @@ async function runGenerator(options) {
       (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(configOutputPath), { recursive: true });
       (0, import_node_fs.writeFileSync)(configOutputPath, adminConfigContent, "utf-8");
       console.info(`Admin config generated: ${configOutputPath}`);
+      formatWithPrettier(typesOutputPath, configOutputPath);
     } catch (error) {
       console.error(`Error generating:`, error);
       throw error;

package/generators/generator.js

@@ -5,12 +5,26 @@ import { dirname, resolve, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // libs/core/src/lib/fields/field.types.ts
+function isNamedTab(tab) {
+  return typeof tab.name === "string" && tab.name.length > 0;
+}
 function flattenDataFields(fields) {
   const result = [];
   for (const field of fields) {
     if (field.type === "tabs") {
       for (const tab of field.tabs) {
-        result.push(...flattenDataFields(tab.fields));
+        if (isNamedTab(tab)) {
+          const syntheticGroup = {
+            name: tab.name,
+            type: "group",
+            label: tab.label,
+            description: tab.description,
+            fields: tab.fields
+          };
+          result.push(syntheticGroup);
+        } else {
+          result.push(...flattenDataFields(tab.fields));
+        }
       }
     } else if (field.type === "collapsible" || field.type === "row") {
       result.push(...flattenDataFields(field.fields));
@@ -231,11 +245,7 @@ function generateTypes(config) {
     const hasTimestamps = collection.timestamps !== false;
     for (const field of dataFields) {
       if (field.type === "blocks") {
-        const blockResult = generateBlockTypes(
-          collection.slug,
-          field.name,
-          field
-        );
+        const blockResult = generateBlockTypes(collection.slug, field.name, field);
         blockDeclarations.push(blockResult.declarations);
       }
     }
@@ -249,11 +259,7 @@ function generateTypes(config) {
       const optional = field.required ? "" : "?";
       const propName = needsQuoting2(field.name) ? safeQuote(field.name) : field.name;
       if (field.type === "blocks") {
-        const blockResult = generateBlockTypes(
-          collection.slug,
-          field.name,
-          field
-        );
+        const blockResult = generateBlockTypes(collection.slug, field.name, field);
         lines.push(`  ${propName}${optional}: ${blockResult.unionTypeName}[];`);
       } else {
         const tsType = fieldTypeToTS(field);
@@ -355,6 +361,25 @@ var FIELD_ADMIN_STRIP_KEYS = /* @__PURE__ */ new Set(["condition"]);
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function previewFunctionToTemplate(fn, fields) {
+  try {
+    const sentinel = "__MCMS_FIELD_";
+    const mockDoc = {};
+    for (const field of fields) {
+      mockDoc[field.name] = `${sentinel}${field.name}__`;
+    }
+    const result = fn(mockDoc);
+    if (typeof result !== "string")
+      return true;
+    const template = result.replace(
+      new RegExp(`${sentinel}(\\w+)__`, "g"),
+      (_match, fieldName) => `{${fieldName}}`
+    );
+    return template;
+  } catch {
+    return true;
+  }
+}
 function serializeValue(value, indent = "	") {
   if (value === null)
     return "null";
@@ -523,6 +548,9 @@ function serializeTabsArray(tabs, indent) {
     return "[]";
   const items = tabs.map((tab) => {
     const parts = [];
+    if (tab.name) {
+      parts.push(`${indent}		name: ${JSON.stringify(tab.name)}`);
+    }
     parts.push(`${indent}		label: ${JSON.stringify(tab.label)}`);
     if (tab.description) {
       parts.push(`${indent}		description: ${JSON.stringify(tab.description)}`);
@@ -544,9 +572,13 @@ function serializeCollection(collection, indent = "	") {
   }
   parts.push(`${indent}	fields: ${serializeFieldsArray(collection.fields, indent + "	")}`);
   if (collection.admin) {
-    const adminEntries = Object.entries(collection.admin).filter(
-      ([, v]) => v !== void 0 && typeof v !== "function"
-    );
+    const adminEntries = Object.entries(collection.admin).filter(([, v]) => v !== void 0).map(([k, v]) => {
+      if (k === "preview" && typeof v === "function") {
+        const fn = v;
+        return [k, previewFunctionToTemplate(fn, collection.fields)];
+      }
+      return [k, v];
+    }).filter(([, v]) => typeof v !== "function");
     if (adminEntries.length > 0) {
       const adminObj = Object.fromEntries(adminEntries);
       parts.push(`${indent}	admin: ${serializeValue(adminObj, indent + "	")}`);
@@ -570,6 +602,9 @@ function serializeCollection(collection, indent = "	") {
   if (collection.defaultSort) {
     parts.push(`${indent}	defaultSort: ${JSON.stringify(collection.defaultSort)}`);
   }
+  if (collection.upload !== void 0) {
+    parts.push(`${indent}	upload: ${serializeValue(collection.upload, indent + "	")}`);
+  }
   return `{
 ${parts.join(",\n")},
 ${indent}}`;
@@ -699,6 +734,15 @@ function parseArgs(args) {
   }
   return { configPath, typesOutputPath, configOutputPath, watch: watchMode };
 }
+function formatWithPrettier(...filePaths) {
+  try {
+    execFileSync("npx", ["prettier", "--write", ...filePaths], {
+      stdio: "pipe"
+    });
+  } catch {
+    console.warn("prettier not available \u2014 skipping formatting of generated files");
+  }
+}
 async function runGenerator(options) {
   const configPath = resolve(options.configPath);
   const typesOutputPath = resolve(options.typesOutputPath);
@@ -718,6 +762,7 @@ async function runGenerator(options) {
       mkdirSync(dirname(configOutputPath), { recursive: true });
       writeFileSync(configOutputPath, adminConfigContent, "utf-8");
       console.info(`Admin config generated: ${configOutputPath}`);
+      formatWithPrettier(typesOutputPath, configOutputPath);
     } catch (error) {
       console.error(`Error generating:`, error);
       throw error;

package/index.cjs

@@ -46,6 +46,7 @@ __export(src_exports, {
   getDbAdapter: () => getDbAdapter,
   getGlobals: () => getGlobals,
   getSoftDeleteField: () => getSoftDeleteField,
+  getUploadFieldMapping: () => getUploadFieldMapping,
   group: () => group,
   hasAllRoles: () => hasAllRoles,
   hasAnyRole: () => hasAnyRole,
@@ -53,7 +54,9 @@ __export(src_exports, {
   humanizeFieldName: () => humanizeFieldName,
   isAuthenticated: () => isAuthenticated,
   isLayoutField: () => isLayoutField,
+  isNamedTab: () => isNamedTab,
   isOwner: () => isOwner,
+  isUploadCollection: () => isUploadCollection,
   json: () => json,
   not: () => not,
   number: () => number,
@@ -62,6 +65,8 @@ __export(src_exports, {
   point: () => point,
   radio: () => radio,
   relationship: () => relationship,
+  resolveMigrationConfig: () => resolveMigrationConfig,
+  resolveMigrationMode: () => resolveMigrationMode,
   richText: () => richText,
   row: () => row,
   select: () => select,
@@ -116,6 +121,21 @@ function getSoftDeleteField(config) {
   const sdConfig = config.softDelete;
   return sdConfig.field ?? "deletedAt";
 }
+function isUploadCollection(config) {
+  return config.upload != null;
+}
+function getUploadFieldMapping(config) {
+  if (!isUploadCollection(config))
+    return null;
+  const u = config.upload;
+  return {
+    filename: u.filenameField ?? "filename",
+    mimeType: u.mimeTypeField ?? "mimeType",
+    filesize: u.filesizeField ?? "filesize",
+    path: u.pathField ?? "path",
+    url: u.urlField ?? "url"
+  };
+}
 
 // libs/core/src/lib/fields/field.types.ts
 var LAYOUT_FIELD_TYPES = /* @__PURE__ */ new Set(["tabs", "collapsible", "row"]);
@@ -127,6 +147,9 @@ var ReferentialIntegrityError = class extends Error {
     this.constraint = constraint;
   }
 };
+function isNamedTab(tab) {
+  return typeof tab.name === "string" && tab.name.length > 0;
+}
 function isLayoutField(field) {
   return LAYOUT_FIELD_TYPES.has(field.type);
 }
@@ -135,7 +158,18 @@ function flattenDataFields(fields) {
   for (const field of fields) {
     if (field.type === "tabs") {
       for (const tab of field.tabs) {
-        result.push(...flattenDataFields(tab.fields));
+        if (isNamedTab(tab)) {
+          const syntheticGroup = {
+            name: tab.name,
+            type: "group",
+            label: tab.label,
+            description: tab.description,
+            fields: tab.fields
+          };
+          result.push(syntheticGroup);
+        } else {
+          result.push(...flattenDataFields(tab.fields));
+        }
       }
     } else if (field.type === "collapsible" || field.type === "row") {
       result.push(...flattenDataFields(field.fields));
@@ -415,6 +449,9 @@ var MediaCollection = defineCollection({
     singular: "Media",
     plural: "Media"
   },
+  upload: {
+    mimeTypes: ["image/*", "application/pdf", "video/*", "audio/*"]
+  },
   admin: {
     useAsTitle: "filename",
     defaultColumns: ["filename", "mimeType", "filesize", "createdAt"]
@@ -435,7 +472,6 @@ var MediaCollection = defineCollection({
       description: "File size in bytes"
     }),
     text("path", {
-      required: true,
       label: "Storage Path",
       description: "Path/key where the file is stored",
       admin: {
@@ -546,6 +582,29 @@ function isOwner(ownerField = "createdBy") {
   };
 }
 
+// libs/core/src/lib/migrations.ts
+function resolveMigrationMode(mode) {
+  if (mode === "push" || mode === "migrate")
+    return mode;
+  const env = process.env["NODE_ENV"];
+  if (env === "production")
+    return "migrate";
+  return "push";
+}
+function resolveMigrationConfig(config) {
+  if (!config)
+    return void 0;
+  const mode = resolveMigrationMode(config.mode);
+  return {
+    ...config,
+    directory: config.directory ?? "./migrations",
+    mode,
+    cloneTest: config.cloneTest ?? mode === "migrate",
+    dangerDetection: config.dangerDetection ?? true,
+    autoApply: config.autoApply ?? mode === "push"
+  };
+}
+
 // libs/core/src/lib/config.ts
 var MIN_PASSWORD_LENGTH = 8;
 function defineMomentumConfig(config) {
@@ -576,7 +635,8 @@ function defineMomentumConfig(config) {
       level: config.logging?.level ?? "info",
       format: config.logging?.format ?? "pretty",
       timestamps: config.logging?.timestamps ?? true
-    }
+    },
+    migrations: resolveMigrationConfig(config.migrations)
   };
 }
 function getDbAdapter(config) {
@@ -702,6 +762,7 @@ function createSeedHelpers() {
   getDbAdapter,
   getGlobals,
   getSoftDeleteField,
+  getUploadFieldMapping,
   group,
   hasAllRoles,
   hasAnyRole,
@@ -709,7 +770,9 @@ function createSeedHelpers() {
   humanizeFieldName,
   isAuthenticated,
   isLayoutField,
+  isNamedTab,
   isOwner,
+  isUploadCollection,
   json,
   not,
   number,
@@ -718,6 +781,8 @@ function createSeedHelpers() {
   point,
   radio,
   relationship,
+  resolveMigrationConfig,
+  resolveMigrationMode,
   richText,
   row,
   select,

package/index.js

@@ -40,6 +40,21 @@ function getSoftDeleteField(config) {
   const sdConfig = config.softDelete;
   return sdConfig.field ?? "deletedAt";
 }
+function isUploadCollection(config) {
+  return config.upload != null;
+}
+function getUploadFieldMapping(config) {
+  if (!isUploadCollection(config))
+    return null;
+  const u = config.upload;
+  return {
+    filename: u.filenameField ?? "filename",
+    mimeType: u.mimeTypeField ?? "mimeType",
+    filesize: u.filesizeField ?? "filesize",
+    path: u.pathField ?? "path",
+    url: u.urlField ?? "url"
+  };
+}
 
 // libs/core/src/lib/fields/field.types.ts
 var LAYOUT_FIELD_TYPES = /* @__PURE__ */ new Set(["tabs", "collapsible", "row"]);
@@ -51,6 +66,9 @@ var ReferentialIntegrityError = class extends Error {
     this.constraint = constraint;
   }
 };
+function isNamedTab(tab) {
+  return typeof tab.name === "string" && tab.name.length > 0;
+}
 function isLayoutField(field) {
   return LAYOUT_FIELD_TYPES.has(field.type);
 }
@@ -59,7 +77,18 @@ function flattenDataFields(fields) {
   for (const field of fields) {
     if (field.type === "tabs") {
       for (const tab of field.tabs) {
-        result.push(...flattenDataFields(tab.fields));
+        if (isNamedTab(tab)) {
+          const syntheticGroup = {
+            name: tab.name,
+            type: "group",
+            label: tab.label,
+            description: tab.description,
+            fields: tab.fields
+          };
+          result.push(syntheticGroup);
+        } else {
+          result.push(...flattenDataFields(tab.fields));
+        }
       }
     } else if (field.type === "collapsible" || field.type === "row") {
       result.push(...flattenDataFields(field.fields));
@@ -339,6 +368,9 @@ var MediaCollection = defineCollection({
     singular: "Media",
     plural: "Media"
   },
+  upload: {
+    mimeTypes: ["image/*", "application/pdf", "video/*", "audio/*"]
+  },
   admin: {
     useAsTitle: "filename",
     defaultColumns: ["filename", "mimeType", "filesize", "createdAt"]
@@ -359,7 +391,6 @@ var MediaCollection = defineCollection({
       description: "File size in bytes"
     }),
     text("path", {
-      required: true,
       label: "Storage Path",
       description: "Path/key where the file is stored",
       admin: {
@@ -470,6 +501,29 @@ function isOwner(ownerField = "createdBy") {
   };
 }
 
+// libs/core/src/lib/migrations.ts
+function resolveMigrationMode(mode) {
+  if (mode === "push" || mode === "migrate")
+    return mode;
+  const env = process.env["NODE_ENV"];
+  if (env === "production")
+    return "migrate";
+  return "push";
+}
+function resolveMigrationConfig(config) {
+  if (!config)
+    return void 0;
+  const mode = resolveMigrationMode(config.mode);
+  return {
+    ...config,
+    directory: config.directory ?? "./migrations",
+    mode,
+    cloneTest: config.cloneTest ?? mode === "migrate",
+    dangerDetection: config.dangerDetection ?? true,
+    autoApply: config.autoApply ?? mode === "push"
+  };
+}
+
 // libs/core/src/lib/config.ts
 var MIN_PASSWORD_LENGTH = 8;
 function defineMomentumConfig(config) {
@@ -500,7 +554,8 @@ function defineMomentumConfig(config) {
       level: config.logging?.level ?? "info",
       format: config.logging?.format ?? "pretty",
       timestamps: config.logging?.timestamps ?? true
-    }
+    },
+    migrations: resolveMigrationConfig(config.migrations)
   };
 }
 function getDbAdapter(config) {
@@ -625,6 +680,7 @@ export {
   getDbAdapter,
   getGlobals,
   getSoftDeleteField,
+  getUploadFieldMapping,
   group,
   hasAllRoles,
   hasAnyRole,
@@ -632,7 +688,9 @@ export {
   humanizeFieldName,
   isAuthenticated,
   isLayoutField,
+  isNamedTab,
   isOwner,
+  isUploadCollection,
   json,
   not,
   number,
@@ -641,6 +699,8 @@ export {
   point,
   radio,
   relationship,
+  resolveMigrationConfig,
+  resolveMigrationMode,
   richText,
   row,
   select,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momentumcms/core",
-  "version": "0.1.10",
+  "version": "0.3.0",
   "description": "Core collection config, fields, hooks, and access control for Momentum CMS",
   "license": "MIT",
   "author": "Momentum CMS Contributors",

package/src/generators/generator.d.ts

@@ -31,6 +31,7 @@ interface FieldDefinition {
         editor?: Record<string, unknown>;
     }>;
     tabs?: Array<{
+        name?: string;
         label: string;
         description?: string;
         fields: FieldDefinition[];
@@ -90,6 +91,16 @@ interface CollectionDefinition {
     defaultWhere?: unknown;
     endpoints?: unknown[];
     webhooks?: unknown[];
+    upload?: {
+        mimeTypes?: string[];
+        maxFileSize?: number;
+        directory?: string;
+        filenameField?: string;
+        mimeTypeField?: string;
+        filesizeField?: string;
+        pathField?: string;
+        urlField?: string;
+    };
 }
 interface GlobalDefinition {
     slug: string;

package/src/index.d.ts

@@ -12,3 +12,4 @@ export * from './lib/plugins';
 export * from './lib/storage';
 export * from './lib/seeding';
 export * from './lib/versions';
+export * from './lib/migrations';

package/src/lib/collections/collection.types.d.ts

@@ -74,8 +74,8 @@ export interface AdminConfig {
     description?: string;
     /** Hide from admin navigation */
     hidden?: boolean;
-    /** Enable preview mode */
-    preview?: boolean | ((doc: Record<string, unknown>) => string);
+    /** Enable preview mode. String values are URL templates with {fieldName} placeholders. */
+    preview?: boolean | string | ((doc: Record<string, unknown>) => string);
     /** Custom action buttons displayed in the collection list header (alongside Create button) */
     headerActions?: Array<{
         id: string;
@@ -120,6 +120,24 @@ export interface SoftDeleteConfig {
     /** Auto-purge soft-deleted records after this many days. Undefined means never purge. */
     retentionDays?: number;
 }
+export interface UploadCollectionConfig {
+    /** Allowed MIME types for uploads to this collection (e.g., ['image/*', 'application/pdf']) */
+    mimeTypes?: string[];
+    /** Maximum file size in bytes (overrides global storage.maxFileSize) */
+    maxFileSize?: number;
+    /** Subdirectory within the upload dir for this collection's files */
+    directory?: string;
+    /** Field name for the original filename. @default 'filename' */
+    filenameField?: string;
+    /** Field name for the MIME type. @default 'mimeType' */
+    mimeTypeField?: string;
+    /** Field name for the file size in bytes. @default 'filesize' */
+    filesizeField?: string;
+    /** Field name for the storage path. @default 'path' */
+    pathField?: string;
+    /** Field name for the public URL. @default 'url' */
+    urlField?: string;
+}
 export interface TimestampsConfig {
     /** Add createdAt field */
     createdAt?: boolean;
@@ -188,6 +206,12 @@ export interface CollectionConfig {
     endpoints?: EndpointConfig[];
     /** Webhook subscriptions for this collection */
     webhooks?: WebhookConfig[];
+    /**
+     * Upload configuration. When present, this collection becomes an "upload collection"
+     * where POST /api/{slug} accepts multipart/form-data and auto-populates file metadata fields.
+     * Similar to Payload CMS's upload collection pattern.
+     */
+    upload?: UploadCollectionConfig;
 }
 /** Events that trigger webhooks. */
 export type WebhookEvent = 'afterChange' | 'afterDelete' | 'afterCreate' | 'afterUpdate';

package/src/lib/collections/define-collection.d.ts

@@ -40,6 +40,25 @@ export declare function defineGlobal(config: GlobalConfig): GlobalConfig;
  * @returns The deletedAt field name, or null if soft delete is not enabled
  */
 export declare function getSoftDeleteField(config: CollectionConfig): string | null;
+/**
+ * Check whether a collection is configured as an upload collection.
+ */
+export declare function isUploadCollection(config: CollectionConfig): boolean;
+/**
+ * Resolved field name mapping for upload collection metadata fields.
+ */
+export interface UploadFieldMapping {
+    filename: string;
+    mimeType: string;
+    filesize: string;
+    path: string;
+    url: string;
+}
+/**
+ * Get the resolved upload field mapping for an upload collection.
+ * Returns field names used for auto-populating file metadata, or null for non-upload collections.
+ */
+export declare function getUploadFieldMapping(config: CollectionConfig): UploadFieldMapping | null;
 /**
  * Helper type to extract the document type from a collection
  * Useful for typing API responses and database queries

package/src/lib/collections/index.d.ts

@@ -1,5 +1,5 @@
 export * from './collection.types';
-export { defineCollection, defineGlobal, getSoftDeleteField } from './define-collection';
-export type { InferDocumentType } from './define-collection';
+export { defineCollection, defineGlobal, getSoftDeleteField, isUploadCollection, getUploadFieldMapping, } from './define-collection';
+export type { InferDocumentType, UploadFieldMapping } from './define-collection';
 export { MediaCollection } from './media.collection';
 export type { MediaDocument } from './media.collection';

package/src/lib/config.d.ts

@@ -3,6 +3,7 @@ import type { SeedingConfig, SeedingOptions } from './seeding';
 import type { DocumentVersion, DocumentStatus, VersionQueryOptions, VersionCountOptions, CreateVersionOptions } from './versions';
 import type { MomentumPlugin, PluginAdminRouteDescriptor } from './plugins';
 import type { StorageAdapter } from './storage';
+import type { MigrationConfig, ResolvedMigrationConfig } from './migrations';
 /**
  * Minimum password length for user accounts.
  * Shared across seeding, user sync hooks, and setup middleware.
@@ -13,6 +14,12 @@ export declare const MIN_PASSWORD_LENGTH = 8;
  * This is a placeholder type - actual adapters implement this interface.
  */
 export interface DatabaseAdapter {
+    /**
+     * Database dialect identifier.
+     * Set by the adapter factory (e.g., postgresAdapter sets 'postgresql', sqliteAdapter sets 'sqlite').
+     * Used by the migration CLI to select the correct introspection and SQL generation strategy.
+     */
+    dialect?: 'postgresql' | 'sqlite';
     find(collection: string, query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
     findById(collection: string, id: string): Promise<Record<string, unknown> | null>;
     create(collection: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
@@ -148,6 +155,34 @@ export interface DatabaseAdapter {
      * @returns The full global record after update
      */
     updateGlobal?(slug: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Introspect the current database schema.
+     * Returns table/column metadata for diffing against collection config.
+     */
+    introspect?(): Promise<Record<string, unknown>>;
+    /**
+     * Execute a raw SQL statement (DDL or DML).
+     * Returns the number of affected rows.
+     */
+    executeRaw?(sql: string, params?: unknown[]): Promise<number>;
+    /**
+     * Execute a raw SQL query and return rows.
+     */
+    queryRaw?<T extends Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /**
+     * Clone the database for migration testing.
+     * Returns a connection string or path for the clone.
+     */
+    cloneDatabase?(targetName: string): Promise<string>;
+    /**
+     * Drop a cloned database.
+     */
+    dropClone?(targetName: string): Promise<void>;
+    /**
+     * Acquire an advisory lock for migration safety.
+     * Returns a release function.
+     */
+    acquireMigrationLock?(): Promise<() => Promise<void>>;
 }
 /**
  * Database configuration options.
@@ -327,6 +362,11 @@ export interface MomentumConfig {
      * Plugins run in array order during init/ready, reverse during shutdown.
      */
     plugins?: MomentumPlugin[];
+    /**
+     * Migration system configuration.
+     * When set, enables the schema migration system.
+     */
+    migrations?: MigrationConfig;
 }
 /**
  * Resolved seeding options with defaults applied.
@@ -346,6 +386,7 @@ export interface ResolvedMomentumConfig extends MomentumConfig {
     server: Required<ServerConfig>;
     seeding?: ResolvedSeedingConfig;
     logging: ResolvedLoggingConfig;
+    migrations?: ResolvedMigrationConfig;
 }
 /**
  * Defines Momentum CMS configuration.

package/src/lib/fields/field.types.d.ts

@@ -239,10 +239,16 @@ export interface SlugField extends BaseField {
 }
 /** Tab definition within a tabs layout field */
 export interface TabConfig {
+    /** When present, creates a nested data structure (like a group). Omit for layout-only tabs. */
+    name?: string;
     label: string;
     description?: string;
     fields: Field[];
 }
+/** Type guard: returns true if the tab has a non-empty name (stores nested data). */
+export declare function isNamedTab(tab: TabConfig): tab is TabConfig & {
+    name: string;
+};
 /** Tabs layout field - organizes fields into tabbed sections */
 export interface TabsField extends BaseField {
     type: 'tabs';

package/src/lib/migrations.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Migration Types for Momentum CMS
+ *
+ * Universal (browser + server) types for the migration system.
+ * Server-only implementation lives in @momentumcms/migrations.
+ */
+/**
+ * Configuration for the migration system.
+ * Added to MomentumConfig.migrations when migrations are enabled.
+ */
+export interface MigrationConfig {
+    /**
+     * Directory where migration files are stored.
+     * Relative to the app root.
+     * @default './migrations'
+     */
+    directory?: string;
+    /**
+     * Database operation mode.
+     * - 'push': Dev mode — direct schema sync, no migration files
+     * - 'migrate': Production mode — migration files required
+     * - 'auto': 'push' in development, 'migrate' in production
+     * @default 'auto'
+     */
+    mode?: 'push' | 'migrate' | 'auto';
+    /**
+     * Enable clone-test-apply safety pipeline before applying migrations.
+     * When enabled, migrations are first tested on a database clone.
+     * @default true in migrate mode
+     */
+    cloneTest?: boolean;
+    /**
+     * Enable dangerous operation detection and warnings.
+     * @default true
+     */
+    dangerDetection?: boolean;
+    /**
+     * Automatically apply pending migrations on server start.
+     * Only applies in 'push' mode. Migrate mode always requires explicit CLI commands.
+     * @default true in push mode
+     */
+    autoApply?: boolean;
+}
+/**
+ * Status of an individual applied migration.
+ */
+export interface MigrationStatus {
+    /** Migration filename (without extension) */
+    name: string;
+    /** Batch number (migrations applied together share a batch) */
+    batch: number;
+    /** When the migration was applied (ISO string) */
+    appliedAt: string;
+    /** SHA-256 checksum of the migration file */
+    checksum: string;
+    /** How long the migration took to execute (ms) */
+    executionMs: number;
+}
+/**
+ * Overall migration system status (browser-safe for admin UI).
+ */
+export interface MigrationSystemStatus {
+    /** Whether the database schema matches the collection config */
+    inSync: boolean;
+    /** Number of pending (unapplied) migrations */
+    pending: number;
+    /** List of applied migrations */
+    applied: MigrationStatus[];
+    /** Current migration mode */
+    mode: 'push' | 'migrate';
+}
+/**
+ * Severity levels for dangerous operation warnings.
+ */
+export type DangerSeverity = 'warning' | 'destructive' | 'irreversible';
+/**
+ * Resolved migration config with defaults applied.
+ */
+export interface ResolvedMigrationConfig extends MigrationConfig {
+    directory: string;
+    mode: 'push' | 'migrate';
+    cloneTest: boolean;
+    dangerDetection: boolean;
+    autoApply: boolean;
+}
+/**
+ * Resolve the effective migration mode from config and environment.
+ */
+export declare function resolveMigrationMode(mode: MigrationConfig['mode']): 'push' | 'migrate';
+/**
+ * Resolve migration config with defaults applied.
+ */
+export declare function resolveMigrationConfig(config: MigrationConfig | undefined): ResolvedMigrationConfig | undefined;