@manablox/db 0.1.0

package/src/repositories/content.ts

@@ -0,0 +1,758 @@
+import { type ContentStatus, type ContentTypeRegistry, ManabloxError } from '@manablox/core';
+import { and, eq, getTableColumns, inArray, type SQL, sql } from 'drizzle-orm';
+import type { Database } from '../client.js';
+import { idToLabel } from '../columns.js';
+import {
+  buildContentWhere,
+  buildOrderBy,
+  type ContentFilter,
+  type ContentSort,
+  type Pagination,
+} from '../query.js';
+import {
+  type ContentRow,
+  contents,
+  contentVersions,
+  publishedContents,
+  spaces,
+} from '../schema.js';
+
+export type { ContentFilter, ContentSort, Pagination };
+
+export interface ContentWriteData {
+  id?: string | undefined;
+  spaceId: string;
+  typeId: string;
+  locale: string;
+  localizationId?: string | undefined;
+  parentId?: string | null | undefined;
+  title: string;
+  slug: string;
+  fields: Record<string, unknown>;
+  searchText?: string | undefined;
+  visibleInMenu?: boolean | undefined;
+  position?: number | undefined;
+  status?: ContentStatus | undefined;
+  /** Whether the content type contributes its slug to descendants' permalinks. */
+  hasSlug: boolean;
+  actorId?: string | null | undefined;
+  /** Expected current version; a mismatch raises `content.version.conflict`. */
+  expectedVersion?: number | undefined;
+}
+
+export interface TreeNode {
+  content: ContentRow;
+  depth: number;
+  children: TreeNode[];
+}
+
+export interface Paginated<T> {
+  items: T[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export class ContentRepository {
+  constructor(
+    private readonly db: Database,
+    private readonly registry: ContentTypeRegistry,
+  ) {}
+
+  // -------------------------------------------------------------------------
+  // Reads
+  // -------------------------------------------------------------------------
+
+  async findById(id: string, published = false): Promise<ContentRow | null> {
+    const table = published ? publishedContents : contents;
+    const rows = await this.db.select().from(table).where(eq(table.id, id)).limit(1);
+    return (rows[0] as ContentRow | undefined) ?? null;
+  }
+
+  /**
+   * `spaceId` bounds a lookup by id to one tenant.
+   *
+   * The delivery API takes ids straight from the caller, so without it a public instance
+   * pinned to one space still answers for any other space's published documents.
+   */
+  async findManyByIds(
+    ids: string[],
+    published = false,
+    spaceId?: string | null,
+  ): Promise<ContentRow[]> {
+    if (ids.length === 0) return [];
+    const table = published ? publishedContents : contents;
+    const where = spaceId
+      ? and(inArray(table.id, ids), eq(table.spaceId, spaceId))
+      : inArray(table.id, ids);
+    return this.db.select().from(table).where(where) as unknown as Promise<ContentRow[]>;
+  }
+
+  /** Children of many parents in one query, for the tree loader. */
+  async findChildrenOf(
+    parentIds: string[],
+    published = false,
+    spaceId?: string | null,
+  ): Promise<ContentRow[]> {
+    if (parentIds.length === 0) return [];
+    const table = published ? publishedContents : contents;
+    const where = spaceId
+      ? and(inArray(table.parentId, parentIds), eq(table.spaceId, spaceId))
+      : inArray(table.parentId, parentIds);
+    return this.db
+      .select()
+      .from(table)
+      .where(where)
+      .orderBy(sql`${table.position} asc, ${table.title} asc`) as unknown as Promise<ContentRow[]>;
+  }
+
+  async findByPermalink(
+    spaceId: string,
+    locale: string,
+    permalink: string,
+    published = true,
+  ): Promise<ContentRow | null> {
+    // The root path names no document of its own; the space says which one it is.
+    if (permalink === '') return this.findHome(spaceId, locale, published);
+
+    const table = published ? publishedContents : contents;
+    const rows = await this.db
+      .select()
+      .from(table)
+      .where(
+        and(eq(table.spaceId, spaceId), eq(table.locale, locale), eq(table.permalink, permalink)),
+      )
+      .limit(1);
+    return (rows[0] as ContentRow | undefined) ?? null;
+  }
+
+  /**
+   * The document a space nominates as its home, in one locale.
+   *
+   * `settings.homeContentId` names a single row, which belongs to one locale. Every
+   * translation of that document shares its `localizationId`, so the requested locale is
+   * resolved through that rather than by pinning one row per language.
+   */
+  async findHome(spaceId: string, locale: string, published = true): Promise<ContentRow | null> {
+    const [space] = await this.db
+      .select({ settings: spaces.settings })
+      .from(spaces)
+      .where(eq(spaces.id, spaceId))
+      .limit(1);
+
+    const homeId = space?.settings?.homeContentId;
+    if (typeof homeId !== 'string') return null;
+
+    // Always from `contents`: the nominated row may itself be unpublished, and its
+    // localization group is what the lookup below actually needs.
+    const [nominated] = await this.db
+      .select({ localizationId: contents.localizationId })
+      .from(contents)
+      .where(and(eq(contents.id, homeId), eq(contents.spaceId, spaceId)))
+      .limit(1);
+    if (!nominated) return null;
+
+    const table = published ? publishedContents : contents;
+    const rows = await this.db
+      .select()
+      .from(table)
+      .where(
+        and(
+          eq(table.spaceId, spaceId),
+          eq(table.locale, locale),
+          eq(table.localizationId, nominated.localizationId),
+        ),
+      )
+      .limit(1);
+    return (rows[0] as ContentRow | undefined) ?? null;
+  }
+
+  /**
+   * Every other row in a document's localization group — its translations.
+   */
+  async localizationSiblings(
+    spaceId: string,
+    localizationId: string,
+    excludeId?: string,
+  ): Promise<ContentRow[]> {
+    const rows = await this.db
+      .select()
+      .from(contents)
+      .where(and(eq(contents.spaceId, spaceId), eq(contents.localizationId, localizationId)));
+    const all = rows as unknown as ContentRow[];
+    return excludeId ? all.filter((row) => row.id !== excludeId) : all;
+  }
+
+  /**
+   * Merges a few field values into rows without touching the rest of the document.
+   *
+   * Used to carry a non-localized field across a document's translations: a jsonb `||`
+   * so concurrent edits to *other* fields on those rows are not clobbered.
+   */
+  async patchFields(ids: string[], patch: Record<string, unknown>): Promise<void> {
+    if (ids.length === 0 || Object.keys(patch).length === 0) return;
+    await this.db
+      .update(contents)
+      .set({
+        fields: sql`${contents.fields} || ${JSON.stringify(patch)}::jsonb`,
+        updatedAt: new Date(),
+      })
+      .where(inArray(contents.id, ids));
+  }
+
+  async list(
+    filter: ContentFilter,
+    pagination: Pagination,
+    sorts: ContentSort[] = [],
+    published = false,
+  ): Promise<Paginated<ContentRow>> {
+    const table = published ? publishedContents : contents;
+    const where = buildContentWhere(table, filter, this.registry);
+
+    // A window count rides along with the page, so pagination is one round trip.
+    const rows = await this.db
+      .select({ ...getTableColumns(table), total: sql<number>`count(*) over ()::int` })
+      .from(table)
+      .where(where)
+      .orderBy(buildOrderBy(sorts))
+      .limit(pagination.limit)
+      .offset(pagination.offset);
+
+    const items = rows as Array<ContentRow & { total: number }>;
+    return {
+      items: items.map(({ total: _total, ...row }) => row as ContentRow),
+      total: items[0]?.total ?? 0,
+      limit: pagination.limit,
+      offset: pagination.offset,
+    };
+  }
+
+  /**
+   * The whole tree below `rootId` in **one** query: a GiST-indexed `path <@ root`
+   * returns every descendant, and `nlevel()` gives the depth to rebuild the hierarchy.
+   */
+  async tree(
+    spaceId: string,
+    locale: string,
+    rootId: string | null = null,
+    maxDepth = 32,
+    published = false,
+  ): Promise<TreeNode[]> {
+    const table = published ? publishedContents : contents;
+
+    const scope = rootId
+      ? sql`and ${table.path} <@ (select path from ${table} where id = ${rootId}::uuid)
+             and ${table.id} <> ${rootId}::uuid`
+      : sql``;
+
+    const depthLimit = rootId
+      ? sql`and nlevel(${table.path}) <= (select nlevel(path) from ${table} where id = ${rootId}::uuid) + ${maxDepth}`
+      : sql`and nlevel(${table.path}) <= ${maxDepth}`;
+
+    const rows = await this.db
+      .select({ ...getTableColumns(table), depth: sql<number>`nlevel(${table.path})::int` })
+      .from(table)
+      .where(
+        sql`${table.spaceId} = ${spaceId}::uuid and ${table.locale} = ${locale} ${scope} ${depthLimit}`,
+      )
+      .orderBy(sql`nlevel(${table.path}) asc, ${table.position} asc, ${table.title} asc`);
+
+    return buildTree(rows as Array<ContentRow & { depth: number }>, rootId);
+  }
+
+  /** Ancestors of a node, root first — read straight off the materialised path. */
+  async ancestors(id: string, published = false): Promise<ContentRow[]> {
+    const table = published ? publishedContents : contents;
+    const rows = await this.db
+      .select(getTableColumns(table))
+      .from(table)
+      .where(
+        sql`${table.path} @> (select path from ${table} where id = ${id}::uuid)
+            and ${table.id} <> ${id}::uuid`,
+      )
+      .orderBy(sql`nlevel(${table.path}) asc`);
+    return rows as ContentRow[];
+  }
+
+  // -------------------------------------------------------------------------
+  // Writes
+  // -------------------------------------------------------------------------
+
+  async create(data: ContentWriteData): Promise<ContentRow> {
+    return this.db.transaction(async (tx) => {
+      const id = data.id ?? crypto.randomUUID();
+      const parentPath = await this.parentPath(tx as unknown as Database, data.parentId ?? null);
+      const path = parentPath ? `${parentPath}.${idToLabel(id)}` : idToLabel(id);
+      const parentPrefix = await this.parentPermalinkPath(
+        tx as unknown as Database,
+        data.parentId ?? null,
+      );
+      const segment = data.hasSlug ? data.slug : null;
+      const permalinkPath = joinSegment(parentPrefix, segment);
+      const permalink = segment === null ? null : permalinkPath;
+
+      const [row] = await tx
+        .insert(contents)
+        .values({
+          id,
+          spaceId: data.spaceId,
+          typeId: data.typeId,
+          locale: data.locale,
+          localizationId: data.localizationId ?? crypto.randomUUID(),
+          parentId: data.parentId ?? null,
+          title: data.title,
+          slug: data.slug,
+          path,
+          permalink,
+          permalinkPath,
+          permalinkSegment: segment,
+          status: data.status ?? 'draft',
+          visibleInMenu: data.visibleInMenu ?? false,
+          position: data.position ?? 0,
+          fields: data.fields,
+          searchText: data.searchText ?? '',
+          version: 1,
+          createdBy: data.actorId ?? null,
+          updatedBy: data.actorId ?? null,
+        })
+        .returning();
+
+      if (!row) throw new ManabloxError('content.create.failed');
+      await this.snapshot(tx as unknown as Database, row, data.actorId ?? null);
+      return row as ContentRow;
+    });
+  }
+
+  async update(id: string, data: ContentWriteData): Promise<ContentRow> {
+    return this.db.transaction(async (tx) => {
+      const current = await this.lockRow(tx as unknown as Database, id);
+
+      if (data.expectedVersion !== undefined && data.expectedVersion !== current.version) {
+        throw ManabloxError.conflict('content.version.conflict', {
+          expected: data.expectedVersion,
+          actual: current.version,
+        });
+      }
+
+      const parentChanged = (data.parentId ?? null) !== current.parentId;
+      const segment = data.hasSlug ? data.slug : null;
+      const segmentChanged = segment !== current.permalinkSegment;
+
+      if (parentChanged) {
+        await this.assertNotOwnDescendant(tx as unknown as Database, id, data.parentId ?? null);
+      }
+
+      const parentPath = await this.parentPath(tx as unknown as Database, data.parentId ?? null);
+      const newPath = parentPath ? `${parentPath}.${idToLabel(id)}` : idToLabel(id);
+
+      const [row] = await tx
+        .update(contents)
+        .set({
+          typeId: data.typeId,
+          locale: data.locale,
+          parentId: data.parentId ?? null,
+          title: data.title,
+          slug: data.slug,
+          path: newPath,
+          permalinkSegment: segment,
+          fields: data.fields,
+          searchText: data.searchText ?? '',
+          visibleInMenu: data.visibleInMenu ?? current.visibleInMenu,
+          position: data.position ?? current.position,
+          version: current.version + 1,
+          updatedAt: new Date(),
+          updatedBy: data.actorId ?? null,
+        })
+        .where(eq(contents.id, id))
+        .returning();
+
+      if (!row) throw ManabloxError.notFound('content.notFound', { id });
+
+      if (parentChanged) {
+        await this.moveSubtree(tx as unknown as Database, id, current.path, newPath);
+      }
+
+      if (parentChanged || segmentChanged) {
+        await this.recomputePermalinks(tx as unknown as Database, contents, id);
+      }
+
+      const fresh = (await this.findRow(tx as unknown as Database, id)) ?? (row as ContentRow);
+      await this.snapshot(tx as unknown as Database, fresh, data.actorId ?? null);
+      return fresh;
+    });
+  }
+
+  /**
+   * Reparents a subtree with one statement. `subpath(path, nlevel(:oldPath))` is the part
+   * of each descendant's path *below* the moved node; prefixing it with the node's new
+   * path rebases the whole subtree.
+   */
+  /**
+   * Reparents and reorders a node in one transaction.
+   *
+   * Separate from `update` because a drag is a structural change, not an edit: it writes
+   * no field values, takes no version bump and records no snapshot, so an editor open on
+   * the document does not hit a version conflict because someone reordered the tree.
+   *
+   * `position` is the index among the destination's children, clamped to the ends.
+   * Siblings on both sides are renumbered densely afterwards, so positions never drift
+   * into ties that the tree's `position asc, title asc` ordering would resolve by name.
+   */
+  async move(id: string, parentId: string | null, position: number): Promise<ContentRow> {
+    return this.db.transaction(async (tx) => {
+      const db = tx as unknown as Database;
+      const current = await this.findRow(db, id);
+      if (!current) throw ManabloxError.notFound('content.notFound', { id });
+
+      await this.assertNotOwnDescendant(db, id, parentId);
+
+      const parentPath = await this.parentPath(db, parentId);
+      const newPath = parentPath ? `${parentPath}.${idToLabel(id)}` : idToLabel(id);
+      const parentChanged = parentId !== current.parentId;
+
+      // Ordered as the tree renders them, minus the node being moved, so the requested
+      // index refers to the list the user actually saw.
+      const siblings = (await db
+        .select({ id: contents.id })
+        .from(contents)
+        .where(
+          and(
+            eq(contents.spaceId, current.spaceId),
+            eq(contents.locale, current.locale),
+            parentId === null ? sql`${contents.parentId} is null` : eq(contents.parentId, parentId),
+          ),
+        )
+        .orderBy(sql`${contents.position} asc, ${contents.title} asc`)) as { id: string }[];
+
+      const order = siblings.map((row) => row.id).filter((sibling) => sibling !== id);
+      const index = Math.max(0, Math.min(position, order.length));
+      order.splice(index, 0, id);
+
+      await tx
+        .update(contents)
+        .set({ parentId, path: newPath, updatedAt: new Date() })
+        .where(eq(contents.id, id));
+
+      for (const [at, sibling] of order.entries()) {
+        await tx.update(contents).set({ position: at }).where(eq(contents.id, sibling));
+      }
+
+      if (parentChanged) {
+        await this.moveSubtree(db, id, current.path, newPath);
+        await this.recomputePermalinks(db, contents, id);
+
+        // The node left a list; close the gap it left behind.
+        const former = (await db
+          .select({ id: contents.id })
+          .from(contents)
+          .where(
+            and(
+              eq(contents.spaceId, current.spaceId),
+              eq(contents.locale, current.locale),
+              current.parentId === null
+                ? sql`${contents.parentId} is null`
+                : eq(contents.parentId, current.parentId),
+            ),
+          )
+          .orderBy(sql`${contents.position} asc, ${contents.title} asc`)) as { id: string }[];
+        for (const [at, sibling] of former.entries()) {
+          await tx.update(contents).set({ position: at }).where(eq(contents.id, sibling.id));
+        }
+      }
+
+      const fresh = await this.findRow(db, id);
+      if (!fresh) throw ManabloxError.notFound('content.notFound', { id });
+      return fresh;
+    });
+  }
+
+  private async moveSubtree(
+    db: Database,
+    id: string,
+    oldPath: string,
+    newPath: string,
+  ): Promise<void> {
+    await db.execute(sql`
+      update contents
+      set path = ${newPath}::ltree || subpath(path, nlevel(${oldPath}::ltree)),
+          updated_at = now()
+      where path <@ ${oldPath}::ltree and id <> ${id}::uuid
+    `);
+  }
+
+  /**
+   * Recomputes permalinks for a node and everything beneath it in one recursive CTE.
+   * Each level derives from *its own* parent's freshly computed value (`t.pl`), and
+   * `concat_ws` drops NULL segments so a type without a slug is transparent in the path.
+   */
+  private async recomputePermalinks(
+    db: Database,
+    table: typeof contents | typeof publishedContents,
+    rootId: string,
+  ): Promise<void> {
+    const tableName = table === contents ? sql`contents` : sql`published_contents`;
+    await db.execute(sql`
+      with recursive t as (
+        select c.id,
+               c.permalink_segment,
+               concat_ws('/',
+                 nullif(coalesce(
+                   (select p.permalink_path from ${tableName} p where p.id = c.parent_id), ''), ''),
+                 c.permalink_segment
+               ) as prefix
+        from ${tableName} c
+        where c.id = ${rootId}::uuid
+
+        union all
+
+        select ch.id,
+               ch.permalink_segment,
+               concat_ws('/', nullif(t.prefix, ''), ch.permalink_segment) as prefix
+        from ${tableName} ch
+        join t on ch.parent_id = t.id
+      )
+      update ${tableName} target
+      set permalink_path = t.prefix,
+          permalink = case when t.permalink_segment is null then null else nullif(t.prefix, '') end,
+          updated_at = now()
+      from t
+      where target.id = t.id
+        and (target.permalink_path is distinct from t.prefix
+             or target.permalink is distinct from
+                (case when t.permalink_segment is null then null else nullif(t.prefix, '') end))
+    `);
+  }
+
+  /** Deletes a node and its whole subtree, in both the draft and published tables. */
+  async delete(id: string): Promise<number> {
+    return this.db.transaction(async (tx) => {
+      const current = await this.findRow(tx as unknown as Database, id);
+      if (!current) throw ManabloxError.notFound('content.notFound', { id });
+
+      await tx.execute(sql`
+        delete from published_contents
+        where path <@ (select path from contents where id = ${id}::uuid)
+      `);
+
+      const deleted = await tx
+        .delete(contents)
+        .where(sql`${contents.path} <@ ${current.path}::ltree`)
+        .returning({ id: contents.id });
+
+      return deleted.length;
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Publishing
+  // -------------------------------------------------------------------------
+
+  /**
+   * Copies a draft into the delivery projection inside one transaction, so a reader
+   * never observes a partially published tree.
+   */
+  async publish(id: string, actorId: string | null = null): Promise<ContentRow> {
+    return this.db.transaction(async (tx) => {
+      const row = await this.findRow(tx as unknown as Database, id);
+      if (!row) throw ManabloxError.notFound('content.notFound', { id });
+
+      const publishedAt = new Date();
+      // `db.execute` binds parameters through postgres.js's unsafe path, which has no
+      // Date serialiser — pass an ISO string and let Postgres cast it.
+      const publishedAtIso = publishedAt.toISOString();
+
+      await tx.execute(sql`
+        insert into published_contents (
+          id, space_id, type_id, locale, localization_id, parent_id, title, slug, path,
+          permalink, permalink_path, permalink_segment, status, visible_in_menu, position, fields,
+          search_text, version, source_version, created_at, updated_at, created_by,
+          updated_by, published_at
+        )
+        select id, space_id, type_id, locale, localization_id, parent_id, title, slug, path,
+               permalink, permalink_path, permalink_segment, 'published', visible_in_menu, position, fields,
+               search_text, version, version, created_at, now(), created_by,
+               ${actorId}::uuid, ${publishedAtIso}::timestamptz
+        from contents where id = ${id}::uuid
+        on conflict (id) do update set
+          type_id = excluded.type_id,
+          locale = excluded.locale,
+          parent_id = excluded.parent_id,
+          title = excluded.title,
+          slug = excluded.slug,
+          path = excluded.path,
+          permalink = excluded.permalink,
+          permalink_path = excluded.permalink_path,
+          permalink_segment = excluded.permalink_segment,
+          status = 'published',
+          visible_in_menu = excluded.visible_in_menu,
+          position = excluded.position,
+          fields = excluded.fields,
+          search_text = excluded.search_text,
+          version = excluded.version,
+          source_version = excluded.version,
+          updated_at = now(),
+          updated_by = excluded.updated_by,
+          published_at = excluded.published_at
+      `);
+
+      // Descendants already live in the projection may sit under a stale permalink.
+      await this.recomputePermalinks(tx as unknown as Database, publishedContents, id);
+
+      const [updated] = await tx
+        .update(contents)
+        .set({ status: 'published', publishedAt, updatedBy: actorId })
+        .where(eq(contents.id, id))
+        .returning();
+
+      return updated as ContentRow;
+    });
+  }
+
+  async unpublish(id: string): Promise<void> {
+    await this.db.transaction(async (tx) => {
+      await tx.execute(sql`
+        delete from published_contents
+        where path <@ (select path from contents where id = ${id}::uuid)
+      `);
+      await tx
+        .update(contents)
+        .set({ status: 'draft', publishedAt: null })
+        .where(eq(contents.id, id));
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Versions
+  // -------------------------------------------------------------------------
+
+  async versions(
+    contentId: string,
+    limit = 50,
+  ): Promise<
+    Array<{ version: number; createdAt: Date; createdBy: string | null; label: string | null }>
+  > {
+    const rows = await this.db
+      .select({
+        version: contentVersions.version,
+        createdAt: contentVersions.createdAt,
+        createdBy: contentVersions.createdBy,
+        label: contentVersions.label,
+      })
+      .from(contentVersions)
+      .where(eq(contentVersions.contentId, contentId))
+      .orderBy(sql`version desc`)
+      .limit(limit);
+    return rows;
+  }
+
+  async versionSnapshot(
+    contentId: string,
+    version: number,
+  ): Promise<Record<string, unknown> | null> {
+    const rows = await this.db
+      .select({ snapshot: contentVersions.snapshot })
+      .from(contentVersions)
+      .where(and(eq(contentVersions.contentId, contentId), eq(contentVersions.version, version)))
+      .limit(1);
+    return rows[0]?.snapshot ?? null;
+  }
+
+  private async snapshot(db: Database, row: ContentRow, actorId: string | null): Promise<void> {
+    await db
+      .insert(contentVersions)
+      .values({
+        contentId: row.id,
+        version: row.version,
+        snapshot: row as unknown as Record<string, unknown>,
+        createdBy: actorId,
+      })
+      .onConflictDoNothing();
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  private async findRow(db: Database, id: string): Promise<ContentRow | null> {
+    const rows = await db.select().from(contents).where(eq(contents.id, id)).limit(1);
+    return (rows[0] as ContentRow | undefined) ?? null;
+  }
+
+  private async lockRow(db: Database, id: string): Promise<ContentRow> {
+    const rows = await db.select().from(contents).where(eq(contents.id, id)).limit(1).for('update');
+    const row = rows[0] as ContentRow | undefined;
+    if (!row) throw ManabloxError.notFound('content.notFound', { id });
+    return row;
+  }
+
+  private async parentPath(db: Database, parentId: string | null): Promise<string | null> {
+    if (!parentId) return null;
+    const rows = await db
+      .select({ path: contents.path })
+      .from(contents)
+      .where(eq(contents.id, parentId))
+      .limit(1);
+    const path = rows[0]?.path;
+    if (!path) throw ManabloxError.notFound('content.parent.notFound', { id: parentId });
+    return path;
+  }
+
+  private async parentPermalinkPath(db: Database, parentId: string | null): Promise<string> {
+    if (!parentId) return '';
+    const rows = await db
+      .select({ permalinkPath: contents.permalinkPath })
+      .from(contents)
+      .where(eq(contents.id, parentId))
+      .limit(1);
+    return rows[0]?.permalinkPath ?? '';
+  }
+
+  /** Guards against making a node its own ancestor, which would orphan the subtree. */
+  private async assertNotOwnDescendant(
+    db: Database,
+    id: string,
+    parentId: string | null,
+  ): Promise<void> {
+    if (!parentId) return;
+    if (parentId === id) throw ManabloxError.badRequest('content.parent.self');
+
+    const rows = await db
+      .select({
+        cycle: sql<boolean>`exists (
+          select 1 from contents p
+          where p.id = ${parentId}::uuid
+            and p.path <@ (select path from contents where id = ${id}::uuid)
+        )`,
+      })
+      .from(sql`(select 1) as _`);
+
+    if (rows[0]?.cycle) throw ManabloxError.badRequest('content.parent.cycle', { id, parentId });
+  }
+}
+
+export function buildTree(
+  rows: Array<ContentRow & { depth: number }>,
+  rootId: string | null,
+): TreeNode[] {
+  const nodes = new Map<string, TreeNode>();
+  for (const row of rows) {
+    const { depth, ...content } = row;
+    nodes.set(row.id, { content: content as ContentRow, depth, children: [] });
+  }
+
+  const roots: TreeNode[] = [];
+  for (const node of nodes.values()) {
+    const parentId = node.content.parentId;
+    const parent = parentId ? nodes.get(parentId) : undefined;
+    if (parent && parentId !== rootId) parent.children.push(node);
+    else if (parentId === rootId || !parent) roots.push(node);
+  }
+  return roots;
+}
+
+function joinSegment(prefix: string, segment: string | null): string {
+  if (segment === null) return prefix;
+  return prefix ? `${prefix}/${segment}` : segment;
+}
+
+export type { SQL };