@yunsoft/yuncms-core 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunsoft/yuncms-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Core services, schema, authentication, permissions and storage primitives for YunCMS.",
   "license": "MIT",
   "type": "module",

package/src/bootstrap.js

@@ -7,6 +7,9 @@ import { authActionTokensMigration } from './migrations/0004-auth-action-tokens.
 import { defaultPublicRoleMigration } from './migrations/0005-default-public-role.js';
 import { studioSettingsMigration } from './migrations/0006-studio-settings.js';
 import { systemPermissionResourcesMigration } from './migrations/0007-system-permission-resources.js';
+import { studioLogoFileMigration } from './migrations/0008-studio-logo-file.js';
+import { schemaDisplayNamesMigration } from './migrations/0009-schema-display-names.js';
+import { studioFaviconFileMigration } from './migrations/0010-studio-favicon-file.js';
 import { readSchemaVersion } from './schema-version.js';
 import { ensurePublicRole } from './setup.js';
 
@@ -18,6 +21,9 @@ export const CORE_MIGRATIONS = Object.freeze([
   defaultPublicRoleMigration,
   studioSettingsMigration,
   systemPermissionResourcesMigration,
+  studioLogoFileMigration,
+  schemaDisplayNamesMigration,
+  studioFaviconFileMigration,
 ]);
 
 export const REQUIRED_CORE_MIGRATION_IDS = Object.freeze(

package/src/index.js

@@ -2,6 +2,7 @@ export { DEFAULT_SERVER_PORT, loadConfig, loadEnvFileIfPresent } from './config.
 export { createDatabasePool, pingDatabase, closeDatabasePool } from './database.js';
 export { withTransaction, withConnectionTransaction } from './transaction.js';
 export { assertIdentifier, quoteIdentifier } from './identifier.js';
+export { normalizeDisplayName, normalizeSchemaKey, resolveSchemaName } from './schema-key.js';
 export { YunCmsDatabaseError, normalizeDatabaseError, isRetryableDatabaseError } from './errors.js';
 export { withDatabaseRetry } from './retry.js';
 export {
@@ -41,6 +42,7 @@ export { AuditService, redactAuditValue } from './services/audit-service.js';
 export { ItemsService } from './services/items-service.js';
 export { CollectionsService } from './services/collections-service.js';
 export { FieldsService } from './services/fields-service.js';
+export { SystemCollectionFieldsService } from './services/system-collection-fields-service.js';
 export { RelationsService } from './services/relations-service.js';
 export { UsersService } from './services/users-service.js';
 export { RolesService } from './services/roles-service.js';
@@ -85,4 +87,4 @@ export {
   REQUIRED_CORE_MIGRATION_IDS,
   bootstrapDatabase,
   assertDatabaseCompatible,
-} from './bootstrap.js';
+} from './bootstrap.js';

package/src/migrations/0008-studio-logo-file.js

@@ -0,0 +1,10 @@
+export const studioLogoFileMigration = {
+  id: '0008-studio-logo-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+       ADD COLUMN logo_file CHAR(36) NULL AFTER logo_url,
+       ADD KEY idx_yuncms_studio_settings_logo_file (logo_file),
+       ADD CONSTRAINT fk_yuncms_studio_settings_logo_file
+         FOREIGN KEY (logo_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/migrations/0009-schema-display-names.js

@@ -0,0 +1,19 @@
+export const schemaDisplayNamesMigration = {
+  id: '0009-schema-display-names',
+  statements: [
+    `ALTER TABLE yuncms_collections
+      ADD COLUMN name VARCHAR(255) NULL AFTER collection`,
+    `UPDATE yuncms_collections
+      SET name = collection
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_collections
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+    `ALTER TABLE yuncms_fields
+      ADD COLUMN name VARCHAR(255) NULL AFTER field`,
+    `UPDATE yuncms_fields
+      SET name = field
+      WHERE name IS NULL OR TRIM(name) = ''`,
+    `ALTER TABLE yuncms_fields
+      MODIFY COLUMN name VARCHAR(255) NOT NULL`,
+  ],
+};

package/src/migrations/0010-studio-favicon-file.js

@@ -0,0 +1,12 @@
+export const studioFaviconFileMigration = {
+  id: '0010-studio-favicon-file',
+  statements: [
+    `ALTER TABLE yuncms_studio_settings
+      ADD COLUMN favicon_file CHAR(36) NULL AFTER logo_file`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD KEY idx_yuncms_studio_settings_favicon_file (favicon_file)`,
+    `ALTER TABLE yuncms_studio_settings
+      ADD CONSTRAINT fk_yuncms_studio_settings_favicon_file
+      FOREIGN KEY (favicon_file) REFERENCES yuncms_files (id) ON DELETE SET NULL`,
+  ],
+};

package/src/schema-key.js

@@ -0,0 +1,54 @@
+const TURKISH_ASCII = Object.freeze({
+  ç: 'c',
+  Ç: 'c',
+  ğ: 'g',
+  Ğ: 'g',
+  ı: 'i',
+  İ: 'i',
+  ö: 'o',
+  Ö: 'o',
+  ş: 's',
+  Ş: 's',
+  ü: 'u',
+  Ü: 'u',
+});
+
+function schemaNameError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_SCHEMA_NAME';
+  return error;
+}
+
+export function normalizeDisplayName(value, { fallback = null, maxLength = 255 } = {}) {
+  const candidate = typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : '';
+  const normalized = candidate || (typeof fallback === 'string' ? fallback.trim().replace(/\s+/g, ' ') : '');
+  if (!normalized) throw schemaNameError('A display name is required');
+  if (normalized.length > maxLength) throw schemaNameError(`Display name cannot exceed ${maxLength} characters`);
+  return normalized;
+}
+
+export function normalizeSchemaKey(value, { prefix = 'field', maxLength = 64 } = {}) {
+  const source = normalizeDisplayName(value, { maxLength: 512 });
+  const transliterated = [...source].map((character) => TURKISH_ASCII[character] ?? character).join('');
+  let key = transliterated
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_');
+
+  if (!key) throw schemaNameError('Name must contain at least one letter or number');
+  if (/^[0-9]/.test(key)) key = `${prefix}_${key}`;
+  if (key.length > maxLength) key = key.slice(0, maxLength).replace(/_+$/g, '');
+  if (!key) throw schemaNameError('Name cannot be normalized to a schema key');
+  return key;
+}
+
+export function resolveSchemaName({ displayName, key, prefix = 'field' } = {}) {
+  const name = normalizeDisplayName(displayName ?? key);
+  return {
+    name,
+    key: normalizeSchemaKey(key ?? name, { prefix }),
+  };
+}

package/src/schema-metadata-repository.js

@@ -12,7 +12,7 @@ export class SchemaMetadataRepository {
 
   async listCollections() {
     const [rows] = await this.database.query(
-      `SELECT collection, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
+      `SELECT collection, name, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
        FROM yuncms_collections
        ORDER BY collection ASC`,
     );
@@ -21,7 +21,7 @@ export class SchemaMetadataRepository {
 
   async readCollection(collection) {
     const [rows] = await this.database.query(
-      `SELECT collection, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
+      `SELECT collection, name, primary_key, note, singleton, hidden, \`system\`, metadata, created_at, updated_at
        FROM yuncms_collections
        WHERE collection = ?
        LIMIT 1`,
@@ -32,6 +32,7 @@ export class SchemaMetadataRepository {
 
   async createCollection({
     collection,
+    name = collection,
     primaryKey = 'id',
     note = null,
     singleton = false,
@@ -41,10 +42,11 @@ export class SchemaMetadataRepository {
   }) {
     await this.database.query(
       `INSERT INTO yuncms_collections
-       (collection, primary_key, note, singleton, hidden, \`system\`, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+       (collection, name, primary_key, note, singleton, hidden, \`system\`, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         collection,
+        name,
         primaryKey,
         note,
         singleton ? 1 : 0,
@@ -60,6 +62,10 @@ export class SchemaMetadataRepository {
     const assignments = [];
     const params = [];
 
+    if (Object.hasOwn(patch, 'name')) {
+      assignments.push('name = ?');
+      params.push(patch.name);
+    }
     if (Object.hasOwn(patch, 'note')) {
       assignments.push('note = ?');
       params.push(patch.note ?? null);
@@ -96,7 +102,7 @@ export class SchemaMetadataRepository {
 
   async listFields(collection) {
     const [rows] = await this.database.query(
-      `SELECT id, collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata,
+      `SELECT id, collection, field, name, type, required, readonly, hidden, sort, interface, options, schema_metadata,
               created_at, updated_at
        FROM yuncms_fields
        WHERE collection = ?
@@ -108,7 +114,7 @@ export class SchemaMetadataRepository {
 
   async readField(collection, field) {
     const [rows] = await this.database.query(
-      `SELECT id, collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata,
+      `SELECT id, collection, field, name, type, required, readonly, hidden, sort, interface, options, schema_metadata,
               created_at, updated_at
        FROM yuncms_fields
        WHERE collection = ? AND field = ?
@@ -121,6 +127,7 @@ export class SchemaMetadataRepository {
   async createField({
     collection,
     field,
+    name = field,
     type,
     required = false,
     readonly = false,
@@ -137,11 +144,12 @@ export class SchemaMetadataRepository {
     }
     await this.database.query(
       `INSERT INTO yuncms_fields
-       (collection, field, type, required, readonly, hidden, sort, interface, options, schema_metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+       (collection, field, name, type, required, readonly, hidden, sort, interface, options, schema_metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         collection,
         field,
+        name,
         type,
         required ? 1 : 0,
         readonly ? 1 : 0,
@@ -169,6 +177,10 @@ export class SchemaMetadataRepository {
       }
     }
 
+    if (Object.hasOwn(patch, 'name')) {
+      assignments.push('name = ?');
+      params.push(patch.name);
+    }
     if (Object.hasOwn(patch, 'readonly')) {
       assignments.push('readonly = ?');
       params.push(patch.readonly ? 1 : 0);

package/src/services/collections-service.js

@@ -3,13 +3,14 @@ import { randomUUID } from 'node:crypto';
 import { withAdvisoryLock } from '../advisory-lock.js';
 import { assertIdentifier, quoteIdentifier } from '../identifier.js';
 import { SchemaMetadataRepository } from '../schema-metadata-repository.js';
+import { normalizeDisplayName, resolveSchemaName } from '../schema-key.js';
 import { incrementSchemaVersion } from '../schema-version.js';
 import { compileCollectionSystemFields, normalizeCollectionSystemFields } from '../system-fields.js';
 import { withConnectionTransaction } from '../transaction.js';
 import { BaseService } from './base-service.js';
 import { assertSchemaManager } from './schema-access.js';
 
-const COLLECTION_METADATA_KEYS = new Set(['note', 'singleton', 'hidden', 'metadata']);
+const COLLECTION_METADATA_KEYS = new Set(['name', 'note', 'singleton', 'hidden', 'metadata']);
 
 function assertUserCollectionName(collection) {
   assertIdentifier(collection, 'collection name');
@@ -47,6 +48,9 @@ function assertCollectionMetadataPatch(patch) {
       throw invalidSchemaPayload(`Collection ${key} must be a boolean`);
     }
   }
+  if (Object.hasOwn(patch, 'name')) {
+    patch.name = normalizeDisplayName(patch.name);
+  }
   if (Object.hasOwn(patch, 'note') && patch.note != null && typeof patch.note !== 'string') {
     throw invalidSchemaPayload('Collection note must be a string or null');
   }
@@ -93,7 +97,13 @@ export class CollectionsService extends BaseService {
   async createOne(input = {}) {
     assertSchemaManager(this.accountability);
     assertCollectionCreateMetadata(input);
-    const collection = assertUserCollectionName(input.collection);
+    const resolvedName = resolveSchemaName({
+      displayName: input.name ?? input.collection,
+      key: input.collection,
+      prefix: 'collection',
+    });
+    const collection = assertUserCollectionName(resolvedName.key);
+    const name = resolvedName.name;
     const primaryKey = input.primaryKey ?? 'id';
 
     if (primaryKey !== 'id') {
@@ -132,6 +142,7 @@ export class CollectionsService extends BaseService {
         return await withConnectionTransaction(connection, async () => {
           const created = await metadata.createCollection({
             collection,
+            name,
             primaryKey,
             note: input.note ?? null,
             singleton: input.singleton === true,
@@ -145,6 +156,7 @@ export class CollectionsService extends BaseService {
           await metadata.createField({
             collection,
             field: 'id',
+            name: 'ID',
             type: 'uuid',
             required: true,
             readonly: true,

package/src/services/core-services.js

@@ -11,6 +11,7 @@ import { PermissionsService } from './permissions-service.js';
 import { RelationsService } from './relations-service.js';
 import { RolesService } from './roles-service.js';
 import { StudioSettingsService } from './studio-settings-service.js';
+import { SystemCollectionFieldsService } from './system-collection-fields-service.js';
 import { UsersService } from './users-service.js';
 import { createServiceRegistry } from './service-registry.js';
 
@@ -23,6 +24,7 @@ export function createCoreServiceRegistry() {
     ItemsService,
     CollectionsService,
     FieldsService,
+    SystemCollectionFieldsService,
     RelationsService,
     UsersService,
     RolesService,

package/src/services/fields-service.js

@@ -4,12 +4,13 @@ import { withAdvisoryLock } from '../advisory-lock.js';
 import { compileFieldColumn } from '../field-types.js';
 import { assertIdentifier, quoteIdentifier } from '../identifier.js';
 import { SchemaMetadataRepository } from '../schema-metadata-repository.js';
+import { normalizeDisplayName, resolveSchemaName } from '../schema-key.js';
 import { incrementSchemaVersion } from '../schema-version.js';
 import { withConnectionTransaction } from '../transaction.js';
 import { BaseService } from './base-service.js';
 import { assertSchemaManager } from './schema-access.js';
 
-const FIELD_METADATA_KEYS = new Set(['readonly', 'hidden', 'sort', 'interface', 'options']);
+const FIELD_METADATA_KEYS = new Set(['name', 'readonly', 'hidden', 'sort', 'interface', 'options']);
 const FIELD_PHYSICAL_KEYS = new Set([
   'required',
   'defaultValue',
@@ -46,6 +47,7 @@ function assertFieldMetadataPatch(patch) {
   if (Object.keys(patch).length === 0) {
     throw invalidSchemaPayload('Field metadata patch cannot be empty');
   }
+  if (Object.hasOwn(patch, 'name')) patch.name = normalizeDisplayName(patch.name);
 }
 
 function assertPhysicalPatch(patch) {
@@ -150,7 +152,13 @@ export class FieldsService extends BaseService {
   async createOne(collection, input = {}) {
     assertSchemaManager(this.accountability);
     assertIdentifier(collection, 'collection name');
-    const field = assertFieldName(input.field);
+    const resolvedName = resolveSchemaName({
+      displayName: input.name ?? input.field,
+      key: input.field,
+      prefix: 'field',
+    });
+    const field = assertFieldName(resolvedName.key);
+    const name = resolvedName.name;
 
     if (field === 'id') {
       const error = new Error('The id field is created with the collection and cannot be added again');
@@ -196,6 +204,7 @@ export class FieldsService extends BaseService {
           const created = await metadata.createField({
             collection,
             field,
+            name,
             type: input.type,
             required: input.required === true,
             readonly: input.readonly === true,

package/src/services/studio-settings-service.js

@@ -3,6 +3,11 @@ import { BaseService } from './base-service.js';
 const THEMES = new Set(['system', 'light', 'dark']);
 const LOCALES = new Set(['en', 'tr']);
 const ACCENT_PATTERN = /^#[0-9a-f]{6}$/i;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const YUNSOFT_LOGOS = new Set([
+  'https://yunsoft.com/light-logo.png',
+  'https://yunsoft.com/dark-logo.png',
+]);
 
 function invalid(message) {
   const error = new Error(message);
@@ -10,6 +15,12 @@ function invalid(message) {
   return error;
 }
 
+function notFound(message) {
+  const error = new Error(message);
+  error.code = 'NOT_FOUND';
+  return error;
+}
+
 function assertManager(accountability) {
   if (accountability.admin === true || accountability.system === true) return;
   const error = new Error('Studio settings require administrator accountability');
@@ -25,16 +36,17 @@ function normalizeBrandName(value) {
 }
 
 function normalizeLogoUrl(value) {
-  if (typeof value !== 'string' || !value.trim()) throw invalid('Logo URL is required');
-  const normalized = value.trim();
-  if (normalized.length > 512) throw invalid('Logo URL cannot exceed 512 characters');
-  let url;
-  try {
-    url = new URL(normalized);
-  } catch {
-    throw invalid('Logo URL must be a valid URL');
+  const normalized = String(value ?? '').trim();
+  if (!YUNSOFT_LOGOS.has(normalized)) {
+    throw invalid('External logo URLs are not supported; choose an image from Files');
   }
-  if (!['http:', 'https:'].includes(url.protocol)) throw invalid('Logo URL must use HTTP or HTTPS');
+  return normalized;
+}
+
+function normalizeImageFile(value, label) {
+  if (value == null || value === '') return null;
+  const normalized = String(value).trim();
+  if (!UUID_PATTERN.test(normalized)) throw invalid(`${label} file id must be a UUID`);
   return normalized;
 }
 
@@ -60,6 +72,8 @@ function publicSettings(row) {
   return {
     brand_name: row.brand_name,
     logo_url: row.logo_url,
+    logo_file: row.logo_file ?? null,
+    favicon_file: row.favicon_file ?? null,
     accent_color: row.accent_color,
     theme: row.theme,
     default_locale: row.default_locale,
@@ -70,7 +84,7 @@ function publicSettings(row) {
 export class StudioSettingsService extends BaseService {
   async readPublic() {
     const [rows] = await this.database.query(
-      `SELECT brand_name, logo_url, accent_color, theme, default_locale, updated_at
+      `SELECT brand_name, logo_url, logo_file, favicon_file, accent_color, theme, default_locale, updated_at
        FROM yuncms_studio_settings
        WHERE id = 1
        LIMIT 1`,
@@ -89,12 +103,56 @@ export class StudioSettingsService extends BaseService {
     return this.readPublic();
   }
 
+  async readImageAssetContent(settingKey, label) {
+    const settings = await this.readPublic();
+    const fileId = settings[settingKey];
+    if (!fileId) throw notFound(`No file-backed Studio ${label.toLowerCase()} is configured`);
+    if (!this.storage) throw new Error(`StudioSettingsService requires storage to read a file-backed ${label.toLowerCase()}`);
+
+    const [rows] = await this.database.query(
+      `SELECT id, storage, filename_disk, mimetype, filesize
+       FROM yuncms_files
+       WHERE id = ?
+       LIMIT 1`,
+      [fileId],
+    );
+    const file = rows[0];
+    if (!file) throw notFound(`Configured Studio ${label.toLowerCase()} file does not exist`);
+    if (!String(file.mimetype || '').toLowerCase().startsWith('image/')) {
+      throw invalid(`Configured Studio ${label.toLowerCase()} must be an image`);
+    }
+
+    const driver = this.storage.get(file.storage);
+    const contents = await driver.get(file.filename_disk);
+    return { file, contents };
+  }
+
+  async readLogoContent() {
+    return this.readImageAssetContent('logo_file', 'Logo');
+  }
+
+  async readFaviconContent() {
+    return this.readImageAssetContent('favicon_file', 'Favicon');
+  }
+
+  async validateSelectedImage(fileId, label) {
+    if (!fileId) return;
+    const [files] = await this.database.query(
+      'SELECT id, mimetype FROM yuncms_files WHERE id = ? LIMIT 1',
+      [fileId],
+    );
+    if (!files[0]) throw invalid(`Selected ${label.toLowerCase()} file does not exist`);
+    if (!String(files[0].mimetype || '').toLowerCase().startsWith('image/')) {
+      throw invalid(`Selected ${label.toLowerCase()} file must be an image`);
+    }
+  }
+
   async updateOne(patch = {}) {
     assertManager(this.accountability);
     if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw invalid('Studio settings patch must be an object');
 
     const keys = Object.keys(patch);
-    const allowed = new Set(['brand_name', 'logo_url', 'accent_color', 'theme', 'default_locale']);
+    const allowed = new Set(['brand_name', 'logo_url', 'logo_file', 'favicon_file', 'accent_color', 'theme', 'default_locale']);
     if (keys.length === 0 || keys.some((key) => !allowed.has(key))) {
       throw invalid('Studio settings patch contains unsupported properties');
     }
@@ -109,6 +167,18 @@ export class StudioSettingsService extends BaseService {
       assignments.push('logo_url = ?');
       params.push(normalizeLogoUrl(patch.logo_url));
     }
+    if (Object.hasOwn(patch, 'logo_file')) {
+      const fileId = normalizeImageFile(patch.logo_file, 'Logo');
+      await this.validateSelectedImage(fileId, 'Logo');
+      assignments.push('logo_file = ?');
+      params.push(fileId);
+    }
+    if (Object.hasOwn(patch, 'favicon_file')) {
+      const fileId = normalizeImageFile(patch.favicon_file, 'Favicon');
+      await this.validateSelectedImage(fileId, 'Favicon');
+      assignments.push('favicon_file = ?');
+      params.push(fileId);
+    }
     if (Object.hasOwn(patch, 'accent_color')) {
       assignments.push('accent_color = ?');
       params.push(normalizeAccent(patch.accent_color));
@@ -134,6 +204,8 @@ export class StudioSettingsService extends BaseService {
 export const STUDIO_SETTING_DEFAULTS = Object.freeze({
   brand_name: 'YunCMS',
   logo_url: 'https://yunsoft.com/light-logo.png',
+  logo_file: null,
+  favicon_file: null,
   accent_color: '#2563eb',
   theme: 'system',
   default_locale: 'en',

package/src/services/system-collection-fields-service.js

@@ -0,0 +1,122 @@
+import { withAdvisoryLock } from '../advisory-lock.js';
+import { compileFieldColumn } from '../field-types.js';
+import { assertIdentifier, quoteIdentifier } from '../identifier.js';
+import { SchemaMetadataRepository } from '../schema-metadata-repository.js';
+import { resolveSchemaName } from '../schema-key.js';
+import { incrementSchemaVersion } from '../schema-version.js';
+import { isPermissionManagedSystemResource } from '../system-permissions.js';
+import { withConnectionTransaction } from '../transaction.js';
+import { BaseService } from './base-service.js';
+import { assertSchemaManager } from './schema-access.js';
+
+function fieldName(value) {
+  assertIdentifier(value, 'field name');
+  if (value.length > 64) {
+    const error = new Error('Field name cannot exceed 64 characters');
+    error.code = 'INVALID_SCHEMA_PAYLOAD';
+    throw error;
+  }
+  if (value === 'id') {
+    const error = new Error('The id field cannot be replaced');
+    error.code = 'FIELD_EXISTS';
+    throw error;
+  }
+  return value;
+}
+
+function assertExtensibleSystemCollection(collection) {
+  if (!collection?.system || !isPermissionManagedSystemResource(collection)) {
+    const error = new Error(`System collection is not extensible: ${collection?.collection || 'unknown'}`);
+    error.code = 'SYSTEM_SCHEMA_READ_ONLY';
+    throw error;
+  }
+}
+
+function assertSystemExtensionInput(input = {}) {
+  if (input.required === true) {
+    const error = new Error('Custom system collection fields must be optional in V1');
+    error.code = 'SYSTEM_EXTENSION_REQUIRED_UNSUPPORTED';
+    throw error;
+  }
+}
+
+export class SystemCollectionFieldsService extends BaseService {
+  async createOne(collectionName, input = {}) {
+    assertSchemaManager(this.accountability);
+    assertIdentifier(collectionName, 'collection name');
+    assertSystemExtensionInput(input);
+    const resolvedName = resolveSchemaName({
+      displayName: input.name ?? input.field,
+      key: input.field,
+      prefix: 'field',
+    });
+    const field = fieldName(resolvedName.key);
+    const name = resolvedName.name;
+    const compiled = compileFieldColumn({ ...input, required: false });
+
+    return withAdvisoryLock(this.database, 'yuncms:schema', async (connection) => {
+      const metadata = new SchemaMetadataRepository(connection);
+      const collection = await metadata.readCollection(collectionName);
+      if (!collection) {
+        const error = new Error(`Unknown collection: ${collectionName}`);
+        error.code = 'COLLECTION_NOT_FOUND';
+        throw error;
+      }
+      assertExtensibleSystemCollection(collection);
+
+      const existing = await metadata.readField(collectionName, field);
+      if (existing) {
+        const error = new Error(`Field already exists: ${collectionName}.${field}`);
+        error.code = 'FIELD_EXISTS';
+        throw error;
+      }
+
+      const table = quoteIdentifier(collectionName, 'collection name');
+      const column = quoteIdentifier(field, 'field name');
+      let physicalCreated = false;
+
+      try {
+        await connection.query(`ALTER TABLE ${table} ADD COLUMN ${column} ${compiled.sql}`, compiled.params);
+        physicalCreated = true;
+
+        return await withConnectionTransaction(connection, async () => {
+          const created = await metadata.createField({
+            collection: collectionName,
+            field,
+            name,
+            type: input.type,
+            required: false,
+            readonly: input.readonly === true,
+            hidden: input.hidden === true,
+            sort: input.sort ?? null,
+            interface: input.interface ?? null,
+            options: input.options ?? null,
+            schemaMetadata: {
+              ...compiled.schemaMetadata,
+              systemExtension: true,
+            },
+          });
+          const schemaVersion = await incrementSchemaVersion(connection);
+          return { ...created, schemaVersion };
+        });
+      } catch (error) {
+        try {
+          await metadata.deleteField(collectionName, field);
+        } catch (cleanupError) {
+          error.cleanupMetadataError = cleanupError;
+        }
+        if (physicalCreated) {
+          try {
+            await connection.query(`ALTER TABLE ${table} DROP COLUMN ${column}`);
+          } catch (cleanupError) {
+            error.cleanupPhysicalError = cleanupError;
+            error.code ||= 'SCHEMA_PARTIAL_FAILURE';
+          }
+        }
+        throw error;
+      }
+    });
+  }
+}
+
+export { assertExtensibleSystemCollection, assertSystemExtensionInput };