nextly 0.0.1 → 0.0.2-alpha.0

package/dist/chunk-YZNBLFIW.mjs

@@ -0,0 +1,1688 @@
+import {
+  MAX_COMPONENT_NESTING_DEPTH
+} from "./chunk-FQULBZ53.mjs";
+import {
+  PermissionService,
+  RolePermissionService,
+  SYSTEM_RESOURCES
+} from "./chunk-NSEFNNU4.mjs";
+import {
+  BaseRegistryService,
+  assertGlobalResourceSlugAvailable
+} from "./chunk-3FA7FKAV.mjs";
+import {
+  resolveSingleTableName
+} from "./chunk-I4JMR3UR.mjs";
+import {
+  calculateSchemaHash,
+  schemaHashesMatch
+} from "./chunk-5HMZ644B.mjs";
+import {
+  BaseService
+} from "./chunk-2W3DVD7S.mjs";
+import {
+  NextlyError,
+  toDbError
+} from "./chunk-NRUWQ5Z7.mjs";
+
+// src/domains/auth/services/permission-seed-service.ts
+import { eq } from "drizzle-orm";
+var SYSTEM_PERMISSIONS = [
+  {
+    name: "Create Users",
+    slug: "create-users",
+    action: "create",
+    resource: "users",
+    description: "Permission to create users"
+  },
+  {
+    name: "Read Users",
+    slug: "read-users",
+    action: "read",
+    resource: "users",
+    description: "Permission to read users"
+  },
+  {
+    name: "Update Users",
+    slug: "update-users",
+    action: "update",
+    resource: "users",
+    description: "Permission to update users"
+  },
+  {
+    name: "Delete Users",
+    slug: "delete-users",
+    action: "delete",
+    resource: "users",
+    description: "Permission to delete users"
+  },
+  {
+    name: "Create Roles",
+    slug: "create-roles",
+    action: "create",
+    resource: "roles",
+    description: "Permission to create roles"
+  },
+  {
+    name: "Read Roles",
+    slug: "read-roles",
+    action: "read",
+    resource: "roles",
+    description: "Permission to read roles"
+  },
+  {
+    name: "Update Roles",
+    slug: "update-roles",
+    action: "update",
+    resource: "roles",
+    description: "Permission to update roles"
+  },
+  {
+    name: "Delete Roles",
+    slug: "delete-roles",
+    action: "delete",
+    resource: "roles",
+    description: "Permission to delete roles"
+  },
+  {
+    name: "Manage Media",
+    slug: "manage-media",
+    action: "manage",
+    resource: "media",
+    description: "Permission to upload and manage media files"
+  },
+  {
+    name: "Create Media",
+    slug: "create-media",
+    action: "create",
+    resource: "media",
+    description: "Permission to upload media files"
+  },
+  {
+    name: "Read Media",
+    slug: "read-media",
+    action: "read",
+    resource: "media",
+    description: "Permission to view media files"
+  },
+  {
+    name: "Delete Media",
+    slug: "delete-media",
+    action: "delete",
+    resource: "media",
+    description: "Permission to delete media files"
+  },
+  {
+    name: "Manage Settings",
+    slug: "manage-settings",
+    action: "manage",
+    resource: "settings",
+    description: "Permission to manage system settings"
+  },
+  {
+    name: "Read Settings",
+    slug: "read-settings",
+    action: "read",
+    resource: "settings",
+    description: "Permission to read system settings"
+  },
+  {
+    name: "Manage Email Providers",
+    slug: "manage-email-providers",
+    action: "manage",
+    resource: "email-providers",
+    description: "Permission to manage email providers"
+  },
+  {
+    name: "Create Email Providers",
+    slug: "create-email-providers",
+    action: "create",
+    resource: "email-providers",
+    description: "Permission to create email providers"
+  },
+  {
+    name: "Read Email Providers",
+    slug: "read-email-providers",
+    action: "read",
+    resource: "email-providers",
+    description: "Permission to read email providers"
+  },
+  {
+    name: "Delete Email Providers",
+    slug: "delete-email-providers",
+    action: "delete",
+    resource: "email-providers",
+    description: "Permission to delete email providers"
+  },
+  {
+    name: "Manage Email Templates",
+    slug: "manage-email-templates",
+    action: "manage",
+    resource: "email-templates",
+    description: "Permission to manage email templates"
+  },
+  {
+    name: "Create Email Templates",
+    slug: "create-email-templates",
+    action: "create",
+    resource: "email-templates",
+    description: "Permission to create email templates"
+  },
+  {
+    name: "Read Email Templates",
+    slug: "read-email-templates",
+    action: "read",
+    resource: "email-templates",
+    description: "Permission to read email templates"
+  },
+  {
+    name: "Delete Email Templates",
+    slug: "delete-email-templates",
+    action: "delete",
+    resource: "email-templates",
+    description: "Permission to delete email templates"
+  },
+  {
+    name: "Manage API Keys",
+    slug: "manage-api-keys",
+    action: "update",
+    resource: "api-keys",
+    description: "Permission to create and manage API keys"
+  },
+  {
+    name: "Create API Keys",
+    slug: "create-api-keys",
+    action: "create",
+    resource: "api-keys",
+    description: "Permission to create API keys"
+  },
+  {
+    name: "Read API Keys",
+    slug: "read-api-keys",
+    action: "read",
+    resource: "api-keys",
+    description: "Permission to read API keys"
+  },
+  {
+    name: "Delete API Keys",
+    slug: "delete-api-keys",
+    action: "delete",
+    resource: "api-keys",
+    description: "Permission to delete API keys"
+  }
+];
+var PermissionSeedService = class extends BaseService {
+  _permissionService;
+  _rolePermissionService;
+  constructor(adapter, logger) {
+    super(adapter, logger);
+  }
+  get permissionService() {
+    if (!this._permissionService) {
+      this._permissionService = new PermissionService(
+        this.adapter,
+        this.logger
+      );
+    }
+    return this._permissionService;
+  }
+  get rolePermissionService() {
+    if (!this._rolePermissionService) {
+      this._rolePermissionService = new RolePermissionService(
+        this.adapter,
+        this.logger
+      );
+    }
+    return this._rolePermissionService;
+  }
+  /**
+   * Seed all system resource permissions.
+   *
+   * Ensures all permissions from the SYSTEM_PERMISSIONS constant exist.
+   * System permissions cover: users, roles, permissions, media, settings,
+   * email-providers, email-templates.
+   */
+  async seedSystemPermissions() {
+    const result = this.emptySeedResult();
+    for (const perm of SYSTEM_PERMISSIONS) {
+      result.total++;
+      try {
+        const ensureResult = await this.permissionService.ensurePermission(
+          perm.action,
+          perm.resource,
+          perm.name,
+          perm.slug,
+          perm.description
+        );
+        if (ensureResult.created) {
+          result.created++;
+          result.newPermissionIds.push(ensureResult.id);
+        } else {
+          result.skipped++;
+        }
+      } catch {
+        result.errors++;
+      }
+    }
+    return result;
+  }
+  /**
+   * Seed CRUD permissions for a single collection.
+   *
+   * Creates 4 permissions: create, read, update, delete for the given slug.
+   *
+   * @param collectionSlug - The collection slug (e.g., "posts", "products")
+   */
+  async seedCollectionPermissions(collectionSlug) {
+    const result = this.emptySeedResult();
+    const label = this.slugToLabel(collectionSlug);
+    const actions = ["create", "read", "update", "delete"];
+    for (const action of actions) {
+      const actionLabel = action.charAt(0).toUpperCase() + action.slice(1);
+      const name = `${actionLabel} ${label}`;
+      const slug = `${action}-${collectionSlug}`;
+      const description = `Permission to ${action} ${label.toLowerCase()}`;
+      result.total++;
+      try {
+        const ensureResult = await this.permissionService.ensurePermission(
+          action,
+          collectionSlug,
+          name,
+          slug,
+          description
+        );
+        if (ensureResult.created) {
+          result.created++;
+          result.newPermissionIds.push(ensureResult.id);
+        } else {
+          result.skipped++;
+        }
+      } catch {
+        result.errors++;
+      }
+    }
+    return result;
+  }
+  /**
+   * Seed read/update permissions for a single (global document).
+   *
+   * Singles have no create/delete lifecycle — they are auto-created on first
+   * access and cannot be deleted. Only read and update permissions are generated.
+   *
+   * @param singleSlug - The single slug (e.g., "site-settings", "header")
+   */
+  async seedSinglePermissions(singleSlug) {
+    const result = this.emptySeedResult();
+    const label = this.slugToLabel(singleSlug);
+    const actions = ["read", "update"];
+    for (const action of actions) {
+      const actionLabel = action.charAt(0).toUpperCase() + action.slice(1);
+      const name = `${actionLabel} ${label}`;
+      const slug = `${action}-${singleSlug}`;
+      const description = `Permission to ${action} ${label.toLowerCase()}`;
+      result.total++;
+      try {
+        const ensureResult = await this.permissionService.ensurePermission(
+          action,
+          singleSlug,
+          name,
+          slug,
+          description
+        );
+        if (ensureResult.created) {
+          result.created++;
+          result.newPermissionIds.push(ensureResult.id);
+        } else {
+          result.skipped++;
+        }
+      } catch {
+        result.errors++;
+      }
+    }
+    return result;
+  }
+  /**
+   * Seed permissions for ALL dynamic collections.
+   *
+   * Reads all collection slugs from the `dynamic_collections` table
+   * (including plugin-registered collections) and seeds 4 CRUD permissions
+   * for each.
+   */
+  async seedAllCollectionPermissions() {
+    const result = this.emptySeedResult();
+    try {
+      const slugs = await this.getAllCollectionSlugs();
+      for (const slug of slugs) {
+        if (SYSTEM_RESOURCES.includes(slug)) {
+          continue;
+        }
+        const collectionResult = await this.seedCollectionPermissions(slug);
+        this.mergeSeedResult(result, collectionResult);
+      }
+    } catch {
+      this.logger.warn(
+        "Could not read dynamic_collections table \u2014 skipping collection permission seeding."
+      );
+    }
+    return result;
+  }
+  /**
+   * Seed permissions for ALL registered singles.
+   *
+   * Reads all single slugs from the `dynamic_singles` table and seeds
+   * read/update permissions for each.
+   */
+  async seedAllSinglePermissions() {
+    const result = this.emptySeedResult();
+    try {
+      const slugs = await this.getAllSingleSlugs();
+      for (const slug of slugs) {
+        const singleResult = await this.seedSinglePermissions(slug);
+        this.mergeSeedResult(result, singleResult);
+      }
+    } catch {
+      this.logger.warn(
+        "Could not read dynamic_singles table \u2014 skipping single permission seeding."
+      );
+    }
+    return result;
+  }
+  /**
+   * Assign newly created permissions to the super_admin role.
+   *
+   * Ensures the super_admin role retains full access when new permissions
+   * are generated. Only assigns permissions that aren't already assigned.
+   *
+   * @param permissionIds - IDs of newly created permissions to assign
+   */
+  async assignNewPermissionsToSuperAdmin(permissionIds) {
+    if (permissionIds.length === 0) return;
+    try {
+      const { roles } = this.tables;
+      const superAdminRole = await this.db.select({ id: roles.id }).from(roles).where(eq(roles.slug, "super-admin")).limit(1).then(
+        (rows) => rows[0] ?? null
+      );
+      if (!superAdminRole) {
+        this.logger.debug(
+          "super-admin role not found yet \u2014 permissions will be assigned during onboarding."
+        );
+        return;
+      }
+      const roleId = String(superAdminRole.id);
+      for (const permissionId of permissionIds) {
+        const existing = await this.db.query.rolePermissions.findFirst({
+          // Required by Drizzle ORM: relational query `where` callback is not
+          // narrowly typed without importing internal Drizzle helper types.
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          where: (rp, { and: andFn, eq: eqFn }) => andFn(eqFn(rp.roleId, roleId), eqFn(rp.permissionId, permissionId)),
+          columns: { id: true }
+        });
+        if (!existing) {
+          try {
+            const perm = await this.permissionService.getPermissionById(permissionId);
+            await this.rolePermissionService.addPermissionToRole(roleId, {
+              action: perm.action,
+              resource: perm.resource,
+              name: perm.name,
+              slug: perm.slug
+            });
+          } catch {
+          }
+        }
+      }
+      this.logger.info?.(
+        `Assigned ${permissionIds.length} new permission(s) to super-admin role.`
+      );
+    } catch (error) {
+      this.logger.warn(
+        `Failed to assign permissions to super-admin: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Delete all permissions for a specific collection or single.
+   *
+   * Removes all permissions where the resource matches the given slug.
+   * First removes the permissions from all roles, then deletes the permissions.
+   * This is typically called when a collection or single is deleted.
+   *
+   * @param resourceSlug - The collection or single slug (e.g., "posts", "site-settings")
+   * @returns Result with count of deleted permissions
+   */
+  async deletePermissionsForResource(resourceSlug) {
+    const result = this.emptySeedResult();
+    try {
+      const allPerms = await this.permissionService.listPermissions({
+        page: 1,
+        limit: 1e4
+      });
+      const { rolePermissions, permissions } = this.tables;
+      for (const perm of allPerms.data) {
+        if (perm.resource === resourceSlug) {
+          result.total++;
+          try {
+            await this.db.delete(rolePermissions).where(eq(rolePermissions.permissionId, perm.id));
+            await this.db.delete(permissions).where(eq(permissions.id, perm.id));
+            result.created++;
+            this.logger.info?.(
+              `Deleted permission "${perm.slug}" for resource "${resourceSlug}"`
+            );
+          } catch (error) {
+            result.skipped++;
+            this.logger.warn?.(
+              `Error deleting permission "${perm.slug}": ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
+      }
+      if (result.created > 0) {
+        this.logger.info?.(
+          `Deleted ${result.created} permission(s) for resource "${resourceSlug}"`
+        );
+      }
+    } catch (error) {
+      this.logger.warn(
+        `Failed to delete permissions for resource "${resourceSlug}": ${error instanceof Error ? error.message : String(error)}`
+      );
+      result.errors++;
+    }
+    return result;
+  }
+  /**
+   * Remove permissions for dynamic resources that no longer exist.
+   *
+   * This is NOT auto-run — it must be called explicitly to prevent
+   * accidental permission loss. Removes permissions whose resource is not
+   * a system resource and not found in dynamic_collections,
+   * dynamic_singles, or dynamic_components.
+   * First removes permissions from all roles, then deletes the permissions.
+   */
+  async cleanupOrphanedPermissions() {
+    const result = this.emptySeedResult();
+    try {
+      const collectionSlugs = await this.getAllCollectionSlugs();
+      const singleSlugs = await this.getAllSingleSlugs();
+      const componentSlugs = await this.getAllComponentSlugs();
+      const knownResources = /* @__PURE__ */ new Set([
+        ...SYSTEM_RESOURCES,
+        ...collectionSlugs,
+        ...singleSlugs,
+        ...componentSlugs
+      ]);
+      const allPerms = await this.permissionService.listPermissions({
+        page: 1,
+        limit: 1e4
+      });
+      const { rolePermissions, permissions } = this.tables;
+      for (const perm of allPerms.data) {
+        if (!knownResources.has(perm.resource)) {
+          result.total++;
+          try {
+            await this.db.delete(rolePermissions).where(eq(rolePermissions.permissionId, perm.id));
+            await this.db.delete(permissions).where(eq(permissions.id, perm.id));
+            result.created++;
+            this.logger.info?.(
+              `Cleaned up orphaned permission "${perm.slug}" (resource: ${perm.resource})`
+            );
+          } catch (error) {
+            result.skipped++;
+            this.logger.warn?.(
+              `Error cleaning up permission "${perm.slug}": ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
+      }
+      if (result.created > 0) {
+        this.logger.info?.(
+          `Cleaned up ${result.created} orphaned permission(s)`
+        );
+      }
+    } catch (error) {
+      this.logger.warn(
+        `Failed to cleanup orphaned permissions: ${error instanceof Error ? error.message : String(error)}`
+      );
+      result.errors++;
+    }
+    return result;
+  }
+  async getAllCollectionSlugs() {
+    if (!this.tables?.dynamicCollections) return [];
+    const rows = await this.db.select({ slug: this.tables.dynamicCollections.slug }).from(this.tables.dynamicCollections);
+    return rows.map((row) => String(row.slug));
+  }
+  async getAllSingleSlugs() {
+    if (!this.tables?.dynamicSingles) return [];
+    const rows = await this.db.select({ slug: this.tables.dynamicSingles.slug }).from(this.tables.dynamicSingles);
+    return rows.map((row) => String(row.slug));
+  }
+  async getAllComponentSlugs() {
+    if (!this.tables?.dynamicComponents) return [];
+    const rows = await this.db.select({ slug: this.tables.dynamicComponents.slug }).from(this.tables.dynamicComponents);
+    return rows.map((row) => String(row.slug));
+  }
+  slugToLabel(slug) {
+    return slug.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  }
+  emptySeedResult() {
+    return {
+      created: 0,
+      skipped: 0,
+      errors: 0,
+      total: 0,
+      newPermissionIds: []
+    };
+  }
+  mergeSeedResult(parent, child) {
+    parent.created += child.created;
+    parent.skipped += child.skipped;
+    parent.errors += child.errors;
+    parent.total += child.total;
+    parent.newPermissionIds.push(...child.newPermissionIds);
+  }
+};
+
+// src/domains/components/services/component-registry-service.ts
+var ComponentRegistryService = class extends BaseRegistryService {
+  registryTableName = "dynamic_components";
+  resourceType = "Component";
+  tableNamePrefix = "comp_";
+  constructor(adapter, logger) {
+    super(adapter, logger);
+  }
+  getSearchColumns() {
+    return ["slug", "label"];
+  }
+  async getComponentBySlug(slug) {
+    return this.getRecordBySlug(slug);
+  }
+  async getComponent(slug) {
+    return this.getRecordOrThrow(slug);
+  }
+  async getAllComponents(options) {
+    return this.getAllRecords(options);
+  }
+  async listComponents(options) {
+    return this.listRecords(options);
+  }
+  async isLocked(slug) {
+    return this.checkIsLocked(slug);
+  }
+  async updateMigrationStatus(slug, status, migrationId) {
+    return this.updateRecordMigrationStatus(slug, status, migrationId);
+  }
+  async updateMigrationStatusWithVerification(slug, tableName) {
+    return this.updateMigrationStatusWithTableVerification(slug, tableName);
+  }
+  async getPendingMigrations() {
+    return this.getRecordsWithPendingMigrations();
+  }
+  /**
+   * Register a new Component in the registry.
+   *
+   * @throws NextlyError(DUPLICATE) if a Component with the same slug already exists.
+   * @throws NextlyError(DATABASE_ERROR) on insert failure.
+   */
+  async registerComponent(data) {
+    this.logger.debug("Registering Component", { slug: data.slug });
+    const existing = await this.getComponentBySlug(data.slug);
+    if (existing) {
+      throw NextlyError.duplicate({
+        logContext: { reason: "component-slug-conflict", slug: data.slug }
+      });
+    }
+    const now = this.formatDateForDb();
+    const tableName = this.ensureTableNamePrefix(data.tableName);
+    const record = {
+      id: this.generateId(),
+      slug: data.slug,
+      label: data.label,
+      table_name: tableName,
+      description: data.description,
+      fields: JSON.stringify(data.fields),
+      admin: data.admin ? JSON.stringify(data.admin) : null,
+      source: data.source,
+      locked: data.locked ?? data.source === "code" ? 1 : 0,
+      config_path: data.configPath,
+      schema_hash: data.schemaHash,
+      schema_version: data.schemaVersion ?? 1,
+      migration_status: data.migrationStatus ?? "pending",
+      last_migration_id: data.lastMigrationId,
+      created_by: data.createdBy,
+      created_at: now,
+      updated_at: now
+    };
+    try {
+      const result = await this.adapter.insert(
+        this.registryTableName,
+        record,
+        { returning: "*" }
+      );
+      this.logger.info("Component registered", {
+        slug: data.slug,
+        source: data.source
+      });
+      return this.deserializeRecord(result);
+    } catch (error) {
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  async registerComponentInTransaction(tx, data) {
+    const existing = await tx.selectOne(
+      this.registryTableName,
+      {
+        where: this.whereEq("slug", data.slug)
+      }
+    );
+    if (existing) {
+      throw NextlyError.duplicate({
+        logContext: { reason: "component-slug-conflict", slug: data.slug }
+      });
+    }
+    const now = this.formatDateForDb();
+    const tableName = this.ensureTableNamePrefix(data.tableName);
+    const record = {
+      id: this.generateId(),
+      slug: data.slug,
+      label: data.label,
+      table_name: tableName,
+      description: data.description,
+      fields: JSON.stringify(data.fields),
+      admin: data.admin ? JSON.stringify(data.admin) : null,
+      source: data.source,
+      locked: data.locked ?? data.source === "code" ? 1 : 0,
+      config_path: data.configPath,
+      schema_hash: data.schemaHash,
+      schema_version: data.schemaVersion ?? 1,
+      migration_status: data.migrationStatus ?? "pending",
+      last_migration_id: data.lastMigrationId,
+      created_by: data.createdBy,
+      created_at: now,
+      updated_at: now
+    };
+    const result = await tx.insert(
+      this.registryTableName,
+      record,
+      { returning: "*" }
+    );
+    return this.deserializeRecord(result);
+  }
+  /**
+   * Update a Component's metadata.
+   *
+   * @throws NextlyError(NOT_FOUND) when no Component matches the slug.
+   * @throws NextlyError(FORBIDDEN) when the Component is locked and the source isn't "code".
+   */
+  async updateComponent(slug, data, options) {
+    this.logger.debug("Updating Component", { slug });
+    const existing = await this.getComponent(slug);
+    if (existing.locked && options?.source !== "code") {
+      throw NextlyError.forbidden({
+        logContext: {
+          reason: "component-locked",
+          slug,
+          source: options?.source ?? "UI"
+        }
+      });
+    }
+    const updateData = {
+      updated_at: this.formatDateForDb()
+    };
+    if (data.label !== void 0) {
+      updateData.label = data.label;
+    }
+    if (data.description !== void 0) {
+      updateData.description = data.description;
+    }
+    if (data.fields) {
+      updateData.fields = JSON.stringify(data.fields);
+      updateData.schema_version = existing.schemaVersion + 1;
+      updateData.migration_status = data.migrationStatus || "pending";
+    }
+    if (data.admin !== void 0) {
+      updateData.admin = data.admin ? JSON.stringify(data.admin) : null;
+    }
+    if (data.schemaHash) {
+      updateData.schema_hash = data.schemaHash;
+    }
+    if (data.locked !== void 0) {
+      updateData.locked = data.locked ? 1 : 0;
+    }
+    if (data.configPath !== void 0) {
+      updateData.config_path = data.configPath;
+    }
+    try {
+      const results = await this.adapter.update(
+        this.registryTableName,
+        updateData,
+        this.whereEq("slug", slug),
+        { returning: "*" }
+      );
+      if (results.length === 0) {
+        throw NextlyError.notFound({ logContext: { slug } });
+      }
+      this.logger.info("Component updated", { slug });
+      return this.deserializeRecord(results[0]);
+    } catch (error) {
+      if (NextlyError.is(error)) {
+        throw error;
+      }
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  /**
+   * Delete a Component from the registry.
+   */
+  async deleteComponent(slug) {
+    this.logger.debug("Deleting Component", { slug });
+    const existing = await this.getComponent(slug);
+    if (existing.locked) {
+      throw NextlyError.forbidden({
+        logContext: { reason: "component-locked-for-delete", slug }
+      });
+    }
+    const references = await this.findComponentReferences(slug);
+    if (references.length > 0) {
+      throw NextlyError.conflict({
+        reason: "state",
+        logContext: { reason: "component-has-references", slug, references }
+      });
+    }
+    try {
+      await this.dropComponentTable(existing.tableName);
+      await this.adapter.delete(
+        this.registryTableName,
+        this.whereEq("slug", slug)
+      );
+      this.logger.info("Component deleted", { slug });
+    } catch (error) {
+      if (NextlyError.is(error)) {
+        throw error;
+      }
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  // Uses IF EXISTS so the operation is safe even if the table was never created.
+  // PostgreSQL uses CASCADE to drop any dependent objects.
+  async dropComponentTable(tableName) {
+    const q = this.dialect === "mysql" ? "`" : '"';
+    const quotedName = `${q}${tableName}${q}`;
+    const sql = this.dialect === "postgresql" ? `DROP TABLE IF EXISTS ${quotedName} CASCADE` : `DROP TABLE IF EXISTS ${quotedName}`;
+    this.logger.debug("Dropping component table", { tableName });
+    await this.adapter.executeQuery(sql);
+    this.logger.info("Component table dropped", { tableName });
+  }
+  /**
+   * Sync code-first Components with the registry.
+   */
+  async syncCodeFirstComponents(configs) {
+    this.logger.info("Syncing code-first Components", {
+      count: configs.length
+    });
+    const result = {
+      created: [],
+      updated: [],
+      unchanged: [],
+      errors: []
+    };
+    for (const config of configs) {
+      try {
+        const existing = await this.getComponentBySlug(config.slug);
+        const schemaHash = calculateSchemaHash(config.fields);
+        if (!existing) {
+          await this.registerComponent({
+            slug: config.slug,
+            label: config.label,
+            tableName: config.tableName ?? this.generateTableName(config.slug),
+            description: config.description,
+            fields: config.fields,
+            admin: config.admin,
+            source: "code",
+            locked: true,
+            configPath: config.configPath,
+            schemaHash
+          });
+          result.created.push(config.slug);
+        } else if (!schemaHashesMatch(schemaHash, existing.schemaHash)) {
+          await this.updateComponent(
+            config.slug,
+            {
+              label: config.label,
+              description: config.description,
+              fields: config.fields,
+              admin: config.admin,
+              configPath: config.configPath,
+              schemaHash,
+              locked: true
+            },
+            { source: "code" }
+          );
+          result.updated.push(config.slug);
+        } else if (this.adminConfigChanged(config.admin, existing.admin)) {
+          await this.updateComponent(
+            config.slug,
+            {
+              admin: config.admin,
+              locked: true
+            },
+            { source: "code" }
+          );
+          result.updated.push(config.slug);
+        } else {
+          result.unchanged.push(config.slug);
+        }
+      } catch (error) {
+        result.errors.push({
+          slug: config.slug,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    this.logger.info("Code-first Component sync completed", {
+      created: result.created.length,
+      updated: result.updated.length,
+      unchanged: result.unchanged.length,
+      errors: result.errors.length
+    });
+    return result;
+  }
+  /**
+   * Find all references to a Component across Collections, Singles, and other Components.
+   */
+  async findComponentReferences(componentSlug) {
+    this.logger.debug("Checking for component references", {
+      slug: componentSlug
+    });
+    const references = [];
+    try {
+      const collections = await this.adapter.select(
+        "dynamic_collections",
+        { columns: ["slug", "fields"] }
+      );
+      for (const collection of collections) {
+        const slug = collection.slug;
+        const fields = this.parseJsonField(collection.fields);
+        if (fields) {
+          const found = this.scanFieldsForComponentRef(
+            fields,
+            componentSlug,
+            slug,
+            "collection"
+          );
+          references.push(...found);
+        }
+      }
+    } catch (error) {
+      this.logger.debug("Could not scan dynamic_collections for references", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    try {
+      const singles = await this.adapter.select(
+        "dynamic_singles",
+        { columns: ["slug", "fields"] }
+      );
+      for (const single of singles) {
+        const slug = single.slug;
+        const fields = this.parseJsonField(single.fields);
+        if (fields) {
+          const found = this.scanFieldsForComponentRef(
+            fields,
+            componentSlug,
+            slug,
+            "single"
+          );
+          references.push(...found);
+        }
+      }
+    } catch (error) {
+      this.logger.debug("Could not scan dynamic_singles for references", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    try {
+      const components = await this.adapter.select(
+        this.registryTableName,
+        { columns: ["slug", "fields"] }
+      );
+      for (const comp of components) {
+        const slug = comp.slug;
+        if (slug === componentSlug) {
+          continue;
+        }
+        const fields = this.parseJsonField(comp.fields);
+        if (fields) {
+          const found = this.scanFieldsForComponentRef(
+            fields,
+            componentSlug,
+            slug,
+            "component"
+          );
+          references.push(...found);
+        }
+      }
+    } catch (error) {
+      this.logger.debug("Could not scan dynamic_components for references", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    if (references.length > 0) {
+      this.logger.debug("Found component references", {
+        slug: componentSlug,
+        count: references.length,
+        references: references.map(
+          (r) => `${r.entityType}:${r.entitySlug}.${r.fieldPath}`
+        )
+      });
+    }
+    return references;
+  }
+  /**
+   * Enrich field configurations with inline component schemas.
+   */
+  async enrichFieldsWithComponentSchemas(fields, currentDepth = 0) {
+    const slugs = this.collectComponentSlugs(fields);
+    if (slugs.size === 0) {
+      return fields;
+    }
+    const componentMap = await this.fetchComponentsBySlugsBatch([...slugs]);
+    return this.enrichFieldsRecursive(fields, componentMap, currentDepth);
+  }
+  collectComponentSlugs(fields, slugs = /* @__PURE__ */ new Set()) {
+    for (const field of fields) {
+      const fieldType = field.type;
+      if (fieldType === "component") {
+        const componentSlug = field.component;
+        if (componentSlug) {
+          slugs.add(componentSlug);
+        }
+        const componentsArray = field.components;
+        if (Array.isArray(componentsArray)) {
+          for (const slug of componentsArray) {
+            slugs.add(slug);
+          }
+        }
+      }
+      const nestedFields = field.fields;
+      if (Array.isArray(nestedFields)) {
+        this.collectComponentSlugs(nestedFields, slugs);
+      }
+    }
+    return slugs;
+  }
+  async fetchComponentsBySlugsBatch(slugs) {
+    const componentMap = /* @__PURE__ */ new Map();
+    if (slugs.length === 0) {
+      return componentMap;
+    }
+    try {
+      const results = await this.adapter.select(
+        this.registryTableName,
+        {
+          where: {
+            and: [
+              {
+                column: "slug",
+                op: "IN",
+                value: slugs
+              }
+            ]
+          }
+        }
+      );
+      for (const result of results) {
+        const deserialized = this.deserializeRecord(result);
+        componentMap.set(deserialized.slug, deserialized);
+      }
+    } catch (error) {
+      this.logger.error(
+        "[ComponentRegistry.fetchComponentsBySlugsBatch] Database error",
+        {
+          error: error instanceof Error ? error.message : String(error)
+        }
+      );
+    }
+    return componentMap;
+  }
+  async enrichFieldsRecursive(fields, componentMap, currentDepth) {
+    const enrichedFields = [];
+    for (const field of fields) {
+      const fieldType = field.type;
+      const enrichedField = { ...field };
+      if (fieldType === "component") {
+        const componentSlug = field.component;
+        if (componentSlug) {
+          const component = componentMap.get(componentSlug);
+          if (component) {
+            let componentFields = component.fields;
+            if (currentDepth < MAX_COMPONENT_NESTING_DEPTH && Array.isArray(componentFields)) {
+              const nestedSlugs = this.collectComponentSlugs(componentFields);
+              if (nestedSlugs.size > 0) {
+                const missingSlugsFetch = [...nestedSlugs].filter(
+                  (s) => !componentMap.has(s)
+                );
+                if (missingSlugsFetch.length > 0) {
+                  const nestedMap = await this.fetchComponentsBySlugsBatch(missingSlugsFetch);
+                  for (const [slug, record] of nestedMap) {
+                    componentMap.set(slug, record);
+                  }
+                }
+                componentFields = await this.enrichFieldsRecursive(
+                  componentFields,
+                  componentMap,
+                  currentDepth + 1
+                );
+              }
+            }
+            enrichedField.componentFields = componentFields;
+          }
+        }
+        const componentsArray = field.components;
+        if (Array.isArray(componentsArray) && componentsArray.length > 0) {
+          const componentSchemas = {};
+          for (const slug of componentsArray) {
+            const component = componentMap.get(slug);
+            if (component) {
+              let componentFields = component.fields;
+              if (currentDepth < MAX_COMPONENT_NESTING_DEPTH && Array.isArray(componentFields)) {
+                const nestedSlugs = this.collectComponentSlugs(componentFields);
+                if (nestedSlugs.size > 0) {
+                  const missingSlugsFetch = [...nestedSlugs].filter(
+                    (s) => !componentMap.has(s)
+                  );
+                  if (missingSlugsFetch.length > 0) {
+                    const nestedMap = await this.fetchComponentsBySlugsBatch(missingSlugsFetch);
+                    for (const [s, record] of nestedMap) {
+                      componentMap.set(s, record);
+                    }
+                  }
+                  componentFields = await this.enrichFieldsRecursive(
+                    componentFields,
+                    componentMap,
+                    currentDepth + 1
+                  );
+                }
+              }
+              componentSchemas[slug] = {
+                label: component.label,
+                fields: componentFields,
+                admin: component.admin
+              };
+            }
+          }
+          if (Object.keys(componentSchemas).length > 0) {
+            enrichedField.componentSchemas = componentSchemas;
+          }
+        }
+      }
+      const nestedFields = field.fields;
+      if (Array.isArray(nestedFields)) {
+        enrichedField.fields = await this.enrichFieldsRecursive(
+          nestedFields,
+          componentMap,
+          currentDepth
+        );
+      }
+      enrichedFields.push(enrichedField);
+    }
+    return enrichedFields;
+  }
+  parseJsonField(value) {
+    if (!value) {
+      return null;
+    }
+    try {
+      if (typeof value === "string") {
+        return JSON.parse(value);
+      }
+      if (Array.isArray(value)) {
+        return value;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  scanFieldsForComponentRef(fields, targetSlug, entitySlug, entityType, parentPath = "") {
+    const references = [];
+    for (const field of fields) {
+      const fieldName = field.name;
+      if (!fieldName) {
+        continue;
+      }
+      const fieldPath = parentPath ? `${parentPath}.${fieldName}` : fieldName;
+      const fieldType = field.type;
+      if (fieldType === "component") {
+        if (field.component === targetSlug) {
+          references.push({ entityType, entitySlug, fieldName, fieldPath });
+        }
+        const componentsArray = field.components;
+        if (Array.isArray(componentsArray) && componentsArray.includes(targetSlug)) {
+          references.push({ entityType, entitySlug, fieldName, fieldPath });
+        }
+      }
+      if ((fieldType === "repeater" || fieldType === "group") && Array.isArray(field.fields)) {
+        const nested = this.scanFieldsForComponentRef(
+          field.fields,
+          targetSlug,
+          entitySlug,
+          entityType,
+          fieldPath
+        );
+        references.push(...nested);
+      }
+    }
+    return references;
+  }
+  deserializeRecord(record) {
+    const r = record;
+    const fields = r.fields;
+    const admin = r.admin;
+    const tableName = r.table_name || r.tableName;
+    const configPath = r.config_path || r.configPath;
+    const schemaHash = r.schema_hash || r.schemaHash;
+    const schemaVersion = r.schema_version || r.schemaVersion;
+    const migrationStatus = r.migration_status || r.migrationStatus;
+    const lastMigrationId = r.last_migration_id || r.lastMigrationId;
+    const createdBy = r.created_by || r.createdBy;
+    const createdAt = r.created_at || r.createdAt;
+    const updatedAt = r.updated_at || r.updatedAt;
+    return {
+      id: r.id,
+      slug: r.slug,
+      label: r.label,
+      tableName,
+      description: r.description,
+      fields: typeof fields === "string" ? JSON.parse(fields) : fields,
+      admin: admin ? typeof admin === "string" ? JSON.parse(admin) : admin : void 0,
+      source: r.source,
+      locked: Boolean(r.locked),
+      configPath,
+      schemaHash,
+      schemaVersion,
+      migrationStatus,
+      lastMigrationId,
+      createdBy,
+      createdAt: this.normalizeDbTimestamp(createdAt),
+      updatedAt: this.normalizeDbTimestamp(updatedAt)
+    };
+  }
+};
+
+// src/domains/singles/services/single-registry-service.ts
+var SingleRegistryService = class extends BaseRegistryService {
+  registryTableName = "dynamic_singles";
+  resourceType = "Single";
+  tableNamePrefix = "single_";
+  /** Optional PermissionSeedService for auto-permission management. */
+  permissionSeedService;
+  constructor(adapter, logger) {
+    super(adapter, logger);
+  }
+  getSearchColumns() {
+    return ["slug", "label"];
+  }
+  /**
+   * Set the PermissionSeedService for auto-seeding permissions on single changes.
+   * Called from DI registration after both services are constructed.
+   */
+  setPermissionSeedService(service) {
+    this.permissionSeedService = service;
+  }
+  // ============================================================
+  // Public API — Delegates to BaseRegistryService
+  // ============================================================
+  async getSingleBySlug(slug) {
+    return this.getRecordBySlug(slug);
+  }
+  async getSingle(slug) {
+    return this.getRecordOrThrow(slug);
+  }
+  async getAllSingles(options) {
+    return this.getAllRecords(options);
+  }
+  async listSingles(options) {
+    return this.listRecords(options);
+  }
+  async isLocked(slug) {
+    return this.checkIsLocked(slug);
+  }
+  async updateMigrationStatus(slug, status, migrationId) {
+    return this.updateRecordMigrationStatus(slug, status, migrationId);
+  }
+  async updateMigrationStatusWithVerification(slug, tableName) {
+    return this.updateMigrationStatusWithTableVerification(slug, tableName);
+  }
+  async getPendingMigrations() {
+    return this.getRecordsWithPendingMigrations();
+  }
+  // ============================================================
+  // Single-Specific: Registration
+  // ============================================================
+  /**
+   * Register a new Single in the registry.
+   *
+   * @throws NextlyError(DUPLICATE) if a Single with the same slug already exists.
+   * @throws NextlyError(DATABASE_ERROR) on insert failure.
+   */
+  async registerSingle(data) {
+    this.logger.debug("Registering Single", { slug: data.slug });
+    await assertGlobalResourceSlugAvailable(this.adapter, data.slug);
+    const existing = await this.getSingleBySlug(data.slug);
+    if (existing) {
+      throw NextlyError.duplicate({
+        logContext: { reason: "single-slug-conflict", slug: data.slug }
+      });
+    }
+    const fieldsJson = JSON.stringify(data.fields);
+    const schemaHash = data.schemaHash ?? this.computeSimpleHash(fieldsJson);
+    const record = this.buildInsertRecord(data, fieldsJson, schemaHash);
+    try {
+      const result = await this.adapter.insert(
+        this.registryTableName,
+        record,
+        { returning: "*" }
+      );
+      this.logger.info("Single registered", {
+        slug: data.slug,
+        source: data.source
+      });
+      await this.seedPermissionsForSingle(data.slug);
+      return this.deserializeRecord(result);
+    } catch (error) {
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  /**
+   * Register a Single within a transaction.
+   */
+  async registerSingleInTransaction(tx, data) {
+    await assertGlobalResourceSlugAvailable(this.adapter, data.slug);
+    const existing = await tx.selectOne(
+      this.registryTableName,
+      {
+        where: this.whereEq("slug", data.slug)
+      }
+    );
+    if (existing) {
+      throw NextlyError.duplicate({
+        logContext: { reason: "single-slug-conflict", slug: data.slug }
+      });
+    }
+    const fieldsJson = JSON.stringify(data.fields);
+    const record = this.buildInsertRecord(
+      data,
+      fieldsJson,
+      data.schemaHash ?? this.computeSimpleHash(fieldsJson)
+    );
+    const result = await tx.insert(
+      this.registryTableName,
+      record,
+      { returning: "*" }
+    );
+    return this.deserializeRecord(result);
+  }
+  // ============================================================
+  // Single-Specific: Update
+  // ============================================================
+  /**
+   * Update a Single's metadata.
+   *
+   * @throws NextlyError(NOT_FOUND) when no Single matches the slug.
+   * @throws NextlyError(FORBIDDEN) when the Single is locked and the source isn't "code".
+   */
+  async updateSingle(slug, data, options) {
+    this.logger.debug("Updating Single", { slug });
+    const existing = await this.getSingle(slug);
+    const targetSlug = data.slug ?? slug;
+    await assertGlobalResourceSlugAvailable(this.adapter, targetSlug, {
+      currentResourceType: "single",
+      currentResourceId: existing.id
+    });
+    if (existing.locked && options?.source !== "code") {
+      throw NextlyError.forbidden({
+        logContext: {
+          reason: "single-locked",
+          slug,
+          source: options?.source ?? "UI"
+        }
+      });
+    }
+    const updateData = {
+      updated_at: /* @__PURE__ */ new Date()
+    };
+    if (data.label !== void 0) {
+      updateData.label = data.label;
+    }
+    if (data.description !== void 0) {
+      updateData.description = data.description;
+    }
+    if (data.fields) {
+      updateData.fields = JSON.stringify(data.fields);
+      updateData.schema_version = existing.schemaVersion + 1;
+      updateData.migration_status = data.migrationStatus || "pending";
+    }
+    if (data.admin !== void 0) {
+      updateData.admin = data.admin ? JSON.stringify(data.admin) : null;
+    }
+    if (data.accessRules !== void 0) {
+      updateData.access_rules = data.accessRules ? JSON.stringify(data.accessRules) : null;
+    }
+    if (data.schemaHash) {
+      updateData.schema_hash = data.schemaHash;
+    }
+    if (data.locked !== void 0) {
+      updateData.locked = data.locked ? 1 : 0;
+    }
+    if (data.configPath !== void 0) {
+      updateData.config_path = data.configPath;
+    }
+    if (data.status !== void 0) {
+      updateData.status = data.status === true ? 1 : 0;
+    }
+    try {
+      const results = await this.adapter.update(
+        this.registryTableName,
+        updateData,
+        this.whereEq("slug", slug),
+        { returning: "*" }
+      );
+      if (results.length === 0) {
+        throw NextlyError.notFound({ logContext: { slug } });
+      }
+      this.logger.info("Single updated", { slug });
+      return this.deserializeRecord(results[0]);
+    } catch (error) {
+      if (NextlyError.is(error)) {
+        throw error;
+      }
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  // ============================================================
+  // Single-Specific: Delete
+  // ============================================================
+  /**
+   * Delete a Single from the registry.
+   *
+   * Singles represent persistent site-wide config, so deletion requires
+   * `force: true`. Use only for admin/CLI operations to clean up orphans.
+   */
+  async deleteSingle(slug, options) {
+    this.logger.debug("Deleting Single", { slug, force: options?.force });
+    const existing = await this.getSingle(slug);
+    if (!options?.force) {
+      throw NextlyError.forbidden({
+        logContext: {
+          reason: "single-requires-force-delete",
+          slug,
+          hint: "Singles represent persistent site-wide configuration. Pass { force: true } for admin/CLI cleanup."
+        }
+      });
+    }
+    if (existing.locked) {
+      this.logger.warn("Force deleting locked Single", {
+        slug,
+        source: existing.source
+      });
+    }
+    try {
+      const count = await this.adapter.delete(
+        this.registryTableName,
+        this.whereEq("slug", slug)
+      );
+      if (count === 0) {
+        throw NextlyError.notFound({ logContext: { slug } });
+      }
+      this.logger.info("Single deleted", { slug, force: true });
+      if (this.permissionSeedService) {
+        try {
+          const permissionResult = await this.permissionSeedService.deletePermissionsForResource(slug);
+          if (permissionResult.created > 0) {
+            this.logger.info(
+              `Deleted ${permissionResult.created} permission(s) for single "${slug}"`
+            );
+          }
+          if (permissionResult.skipped > 0) {
+            this.logger.warn(
+              `${permissionResult.skipped} permission(s) for "${slug}" could not be deleted (may be assigned to roles)`
+            );
+          }
+        } catch (error) {
+          this.logger.warn(
+            `Failed to cleanup permissions for single "${slug}": ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+    } catch (error) {
+      if (NextlyError.is(error)) {
+        throw error;
+      }
+      throw NextlyError.fromDatabaseError(toDbError(this.dialect, error));
+    }
+  }
+  // ============================================================
+  // Single-Specific: Code-First Sync
+  // ============================================================
+  /**
+   * Sync code-first Singles with the registry.
+   *
+   * Compares schema hashes to detect changes and creates/updates
+   * Singles as needed. Typically called during application startup.
+   */
+  async syncCodeFirstSingles(configs) {
+    this.logger.info("Syncing code-first Singles", {
+      count: configs.length
+    });
+    const result = {
+      created: [],
+      updated: [],
+      unchanged: [],
+      errors: []
+    };
+    for (const config of configs) {
+      try {
+        const existing = await this.getSingleBySlug(config.slug);
+        const schemaHash = calculateSchemaHash(config.fields);
+        if (!existing) {
+          await this.registerSingle({
+            slug: config.slug,
+            label: config.label,
+            // Route through the canonical resolver so registry and DDL paths
+            // never disagree on the single's physical table name, even when
+            // an explicit dbName/tableName is provided without the prefix.
+            tableName: resolveSingleTableName({
+              slug: config.slug,
+              dbName: config.tableName
+            }),
+            description: config.description,
+            fields: config.fields,
+            admin: config.admin,
+            source: "code",
+            locked: true,
+            // Forward Draft/Published flag so code-first Singles that opt
+            // in actually write the column on first sync.
+            status: config.status === true,
+            configPath: config.configPath,
+            schemaHash
+          });
+          result.created.push(config.slug);
+          await this.seedPermissionsForSingle(config.slug);
+        } else if (!schemaHashesMatch(schemaHash, existing.schemaHash) || config.status === true !== (existing.status === true)) {
+          await this.updateSingle(
+            config.slug,
+            {
+              label: config.label,
+              description: config.description,
+              fields: config.fields,
+              admin: config.admin,
+              configPath: config.configPath,
+              schemaHash,
+              locked: true,
+              status: config.status === true
+            },
+            { source: "code" }
+          );
+          result.updated.push(config.slug);
+          await this.seedPermissionsForSingle(config.slug);
+        } else {
+          await this.seedPermissionsForSingle(config.slug);
+          result.unchanged.push(config.slug);
+        }
+      } catch (error) {
+        const handled = await this.handleSyncError(config, error);
+        if (handled.status === "unchanged") {
+          result.unchanged.push(config.slug);
+        } else if (handled.status === "created") {
+          result.created.push(config.slug);
+        } else {
+          result.errors.push({ slug: config.slug, error: handled.error });
+        }
+      }
+    }
+    this.logger.info("Code-first Single sync completed", {
+      created: result.created.length,
+      updated: result.updated.length,
+      unchanged: result.unchanged.length,
+      errors: result.errors.length
+    });
+    return result;
+  }
+  // ============================================================
+  // Abstract Implementation
+  // ============================================================
+  /**
+   * Deserialize a raw DB row into a typed {@link DynamicSingleRecord}.
+   *
+   * Handles snake_case-to-camelCase normalization and JSON column parsing
+   * so callers always receive the canonical record shape regardless of
+   * which adapter returned it.
+   */
+  deserializeRecord(record) {
+    const r = record;
+    const fields = r.fields;
+    const admin = r.admin;
+    const accessRules = r.access_rules ?? r.accessRules;
+    const tableName = r.table_name ?? r.tableName;
+    const configPath = r.config_path ?? r.configPath;
+    const schemaHash = r.schema_hash ?? r.schemaHash;
+    const schemaVersion = r.schema_version ?? r.schemaVersion;
+    const migrationStatus = r.migration_status ?? r.migrationStatus;
+    const lastMigrationId = r.last_migration_id ?? r.lastMigrationId;
+    const createdBy = r.created_by ?? r.createdBy;
+    const createdAt = r.created_at ?? r.createdAt;
+    const updatedAt = r.updated_at ?? r.updatedAt;
+    return {
+      id: r.id,
+      slug: r.slug,
+      label: r.label,
+      tableName,
+      description: r.description,
+      fields: typeof fields === "string" ? JSON.parse(fields) : fields,
+      admin: admin ? typeof admin === "string" ? JSON.parse(admin) : admin : void 0,
+      accessRules: accessRules ? typeof accessRules === "string" ? JSON.parse(accessRules) : accessRules : void 0,
+      source: r.source,
+      locked: Boolean(r.locked),
+      // Why: read the new status meta-column, defaulting to false for legacy
+      // rows written before the column existed.
+      status: Boolean(r.status),
+      configPath,
+      schemaHash,
+      schemaVersion,
+      migrationStatus,
+      lastMigrationId,
+      createdBy,
+      createdAt: this.normalizeDbTimestamp(createdAt),
+      updatedAt: this.normalizeDbTimestamp(updatedAt)
+    };
+  }
+  // ============================================================
+  // Private Helpers
+  // ============================================================
+  /**
+   * Seed read/update permissions for a single and assign to super_admin.
+   * Non-blocking — errors are logged but do not fail the parent operation.
+   */
+  async seedPermissionsForSingle(slug) {
+    if (!this.permissionSeedService) return;
+    try {
+      const result = await this.permissionSeedService.seedSinglePermissions(slug);
+      if (result.newPermissionIds.length > 0) {
+        await this.permissionSeedService.assignNewPermissionsToSuperAdmin(
+          result.newPermissionIds
+        );
+      }
+      if (result.created > 0) {
+        this.logger.info(
+          `Permissions seeded for single "${slug}": ${result.created} created, ${result.skipped} already existed`
+        );
+      }
+    } catch (error) {
+      this.logger.warn(
+        `Failed to seed permissions for single "${slug}": ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Build the common insert record shape for registerSingle and
+   * registerSingleInTransaction. Extracted so both flows stay in sync.
+   */
+  buildInsertRecord(data, fieldsJson, schemaHash) {
+    const now = /* @__PURE__ */ new Date();
+    const tableName = resolveSingleTableName({
+      slug: data.slug,
+      dbName: data.tableName
+    });
+    return {
+      id: this.generateId(),
+      slug: data.slug,
+      label: data.label,
+      table_name: tableName,
+      description: data.description,
+      fields: fieldsJson,
+      admin: data.admin ? JSON.stringify(data.admin) : null,
+      access_rules: data.accessRules ? JSON.stringify(data.accessRules) : null,
+      source: data.source,
+      locked: data.locked ?? data.source === "code" ? 1 : 0,
+      // Persist Draft/Published flag so the Singles edit form shows the
+      // Save Draft / Publish split when the schema opts in.
+      status: data.status === true ? 1 : 0,
+      config_path: data.configPath,
+      schema_hash: schemaHash,
+      schema_version: data.schemaVersion ?? 1,
+      migration_status: data.migrationStatus ?? "pending",
+      last_migration_id: data.lastMigrationId,
+      created_by: data.createdBy,
+      created_at: now,
+      updated_at: now
+    };
+  }
+  /**
+   * Handle an error thrown during code-first sync. Disambiguates
+   * duplicate-key errors (which are recoverable) from hard failures.
+   */
+  async handleSyncError(config, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isDuplicate = message.toLowerCase().includes("already exists") || message.toLowerCase().includes("duplicate") || message.toLowerCase().includes("unique constraint");
+    if (!isDuplicate) {
+      return { status: "error", error: message };
+    }
+    const refetched = await this.getSingleBySlug(config.slug).catch(() => null);
+    if (refetched) {
+      this.logger.warn(
+        `Code-first sync: "${config.slug}" already in DB \u2014 treating as unchanged`,
+        { slug: config.slug }
+      );
+      return { status: "unchanged" };
+    }
+    return {
+      status: "error",
+      error: `Single "${config.slug}" has a table_name conflict in the registry and the expected row could not be refetched: ${message}`
+    };
+  }
+};
+
+export {
+  PermissionSeedService,
+  ComponentRegistryService,
+  SingleRegistryService
+};