@rwdocs/backstage-plugin-rw-backend 0.1.4 → 0.1.6

package/dist/comments/CommentEventPublisher.cjs.js

@@ -0,0 +1,119 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var backstagePluginRwCommon = require('@rwdocs/backstage-plugin-rw-common');
+var snippet = require('../inbox/snippet.cjs.js');
+var mapping = require('../inbox/mapping.cjs.js');
+var author = require('./author.cjs.js');
+var types = require('./types.cjs.js');
+
+class CommentEventPublisher {
+  events;
+  sections;
+  comments;
+  logger;
+  pages;
+  constructor(deps) {
+    this.events = deps.events;
+    this.sections = deps.sections;
+    this.comments = deps.comments;
+    this.logger = deps.logger;
+    this.pages = deps.pages;
+  }
+  async onCommentCreated(row, actorRef) {
+    try {
+      if (row.parent_id === null) {
+        await this.publishOwnerSide(row, actorRef);
+      } else {
+        await this.publishParticipantSide("created", row, row.parent_id, actorRef);
+      }
+    } catch (error) {
+      this.logger.warn(`rw.comments publish (created) failed: ${error}`);
+    }
+  }
+  async onCommentResolved(row, actorRef, actorName) {
+    try {
+      await this.publishParticipantSide("resolved", row, row.id, actorRef, actorName);
+    } catch (error) {
+      this.logger.warn(`rw.comments publish (resolved) failed: ${error}`);
+    }
+  }
+  async resolvePageTitle(siteRef, sectionRef, subpath) {
+    try {
+      return await this.pages.getTitle(siteRef, sectionRef, subpath);
+    } catch (err) {
+      this.logger.warn(`rw.comments: could not resolve page title: ${err}`);
+      return null;
+    }
+  }
+  async publishOwnerSide(row, actorRef) {
+    const section = await this.sections.getSection(row.site_ref, row.section_ref);
+    if (!section || !section.entity_owner_ref) return;
+    const recipients = [section.entity_owner_ref].filter((ref) => ref !== actorRef);
+    if (recipients.length === 0) return;
+    const subpath = types.subpathOf(row.page_ref);
+    const viewerPath = mapping.joinNonEmpty([section.section_path, subpath], "/");
+    const actorName = author.authorFromRow(row).name;
+    const [pageTitle, sectionTitle] = await Promise.all([
+      this.resolvePageTitle(row.site_ref, row.section_ref, subpath),
+      this.resolvePageTitle(row.site_ref, row.section_ref, "")
+    ]);
+    await this.publish("created", "owner", row, row.id, recipients, actorRef, {
+      entityRef: section.entity_ref,
+      viewerPath,
+      actorName,
+      pageTitle,
+      sectionTitle
+    });
+  }
+  async publishParticipantSide(kind, row, rootId, actorRef, resolvedActorName) {
+    const participants = await this.comments.participantsOf(rootId);
+    const recipients = participants.filter((ref) => ref !== actorRef);
+    if (recipients.length === 0) return;
+    const section = await this.sections.getSection(row.site_ref, row.section_ref);
+    const subpath = types.subpathOf(row.page_ref);
+    const viewerPath = section ? mapping.joinNonEmpty([section.section_path, subpath], "/") : subpath;
+    const actorName = kind === "resolved" ? resolvedActorName ?? catalogModel.parseEntityRef(actorRef).name : author.authorFromRow(row).name;
+    const [pageTitle, sectionTitle] = await Promise.all([
+      this.resolvePageTitle(row.site_ref, row.section_ref, subpath),
+      this.resolvePageTitle(row.site_ref, row.section_ref, "")
+    ]);
+    await this.publish(kind, "participants", row, rootId, recipients, actorRef, {
+      entityRef: section?.entity_ref ?? null,
+      viewerPath,
+      actorName,
+      pageTitle,
+      sectionTitle
+    });
+  }
+  async publish(kind, audience, row, rootId, recipients, actorRef, link) {
+    const eventPayload = {
+      kind,
+      audience,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      commentId: row.id,
+      rootId,
+      parentId: row.parent_id,
+      siteRef: row.site_ref,
+      sectionRef: row.section_ref,
+      pageRef: row.page_ref,
+      actorRef,
+      recipients,
+      entityRef: link.entityRef,
+      // Anchor on the thread root, not the triggering row: a reply notification
+      // should open the whole thread (rootId === row.id for top-level + resolve events).
+      deepLinkSuffix: backstagePluginRwCommon.buildCommentDeepLinkSuffix({
+        viewerPath: link.viewerPath,
+        commentId: rootId
+      }),
+      bodySnippet: snippet.snippetFromHtml(row.body_html),
+      actorName: link.actorName,
+      pageTitle: link.pageTitle,
+      sectionTitle: link.sectionTitle
+    };
+    await this.events.publish({ topic: backstagePluginRwCommon.RW_COMMENTS_TOPIC, eventPayload });
+  }
+}
+
+exports.CommentEventPublisher = CommentEventPublisher;
+//# sourceMappingURL=CommentEventPublisher.cjs.js.map

package/dist/comments/CommentEventPublisher.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommentEventPublisher.cjs.js","sources":["../../src/comments/CommentEventPublisher.ts"],"sourcesContent":["import { LoggerService } from \"@backstage/backend-plugin-api\";\nimport { parseEntityRef } from \"@backstage/catalog-model\";\nimport { EventsService } from \"@backstage/plugin-events-node\";\nimport {\n  RW_COMMENTS_TOPIC,\n  CommentEventPayload,\n  CommentEventAudience,\n  buildCommentDeepLinkSuffix,\n} from \"@rwdocs/backstage-plugin-rw-common\";\nimport { SectionsReader } from \"../siteIndex/SectionsReader\";\nimport { PagesReader } from \"../siteIndex/PagesReader\";\nimport { snippetFromHtml } from \"../inbox/snippet\";\nimport { joinNonEmpty } from \"../inbox/mapping\";\nimport { CommentStore } from \"./CommentStore\";\nimport { authorFromRow } from \"./author\";\nimport { CommentRow, subpathOf } from \"./types\";\n\n/** Publishes self-contained `rw.comments` domain events after a comment write commits.\n *  Owns recipient + deep-link resolution (it has the comments + sections tables) so the\n *  notifications module can stay a thin sender. Best-effort: every method catches and\n *  logs, and always resolves, so a publish failure can never affect the comment write.\n *  Callers invoke fire-and-forget. */\nexport class CommentEventPublisher {\n  private readonly events: EventsService;\n  private readonly sections: SectionsReader;\n  private readonly comments: CommentStore;\n  private readonly logger: LoggerService;\n  private readonly pages: PagesReader;\n\n  constructor(deps: {\n    events: EventsService;\n    sections: SectionsReader;\n    comments: CommentStore;\n    logger: LoggerService;\n    pages: PagesReader;\n  }) {\n    this.events = deps.events;\n    this.sections = deps.sections;\n    this.comments = deps.comments;\n    this.logger = deps.logger;\n    this.pages = deps.pages;\n  }\n\n  async onCommentCreated(row: CommentRow, actorRef: string): Promise<void> {\n    try {\n      if (row.parent_id === null) {\n        await this.publishOwnerSide(row, actorRef);\n      } else {\n        await this.publishParticipantSide(\"created\", row, row.parent_id, actorRef);\n      }\n    } catch (error) {\n      this.logger.warn(`rw.comments publish (created) failed: ${error}`);\n    }\n  }\n\n  async onCommentResolved(row: CommentRow, actorRef: string, actorName?: string): Promise<void> {\n    try {\n      // resolve only happens on top-level rows, so the row IS the thread root.\n      await this.publishParticipantSide(\"resolved\", row, row.id, actorRef, actorName);\n    } catch (error) {\n      this.logger.warn(`rw.comments publish (resolved) failed: ${error}`);\n    }\n  }\n\n  private async resolvePageTitle(\n    siteRef: string,\n    sectionRef: string,\n    subpath: string,\n  ): Promise<string | null> {\n    try {\n      return await this.pages.getTitle(siteRef, sectionRef, subpath);\n    } catch (err) {\n      this.logger.warn(`rw.comments: could not resolve page title: ${err}`);\n      return null;\n    }\n  }\n\n  private async publishOwnerSide(row: CommentRow, actorRef: string): Promise<void> {\n    const section = await this.sections.getSection(row.site_ref, row.section_ref);\n    if (!section || !section.entity_owner_ref) return; // new/unowned section: inbox catches it\n    const recipients = [section.entity_owner_ref].filter((ref) => ref !== actorRef);\n    if (recipients.length === 0) return;\n    const subpath = subpathOf(row.page_ref);\n    const viewerPath = joinNonEmpty([section.section_path, subpath], \"/\");\n    const actorName = authorFromRow(row).name;\n    const [pageTitle, sectionTitle] = await Promise.all([\n      this.resolvePageTitle(row.site_ref, row.section_ref, subpath),\n      this.resolvePageTitle(row.site_ref, row.section_ref, \"\"),\n    ]);\n    await this.publish(\"created\", \"owner\", row, row.id, recipients, actorRef, {\n      entityRef: section.entity_ref,\n      viewerPath,\n      actorName,\n      pageTitle,\n      sectionTitle,\n    });\n  }\n\n  private async publishParticipantSide(\n    kind: \"created\" | \"resolved\",\n    row: CommentRow,\n    rootId: string,\n    actorRef: string,\n    resolvedActorName?: string,\n  ): Promise<void> {\n    // participantsOf already returns distinct refs, so no extra dedup is needed here.\n    const participants = await this.comments.participantsOf(rootId);\n    const recipients = participants.filter((ref) => ref !== actorRef);\n    if (recipients.length === 0) return;\n    // The section row provides entityRef (link target) + section_path (path prefix); degrade gracefully if absent: entityRef -> null (module emits no link), viewerPath -> bare subpath.\n    const section = await this.sections.getSection(row.site_ref, row.section_ref);\n    const subpath = subpathOf(row.page_ref);\n    const viewerPath = section ? joinNonEmpty([section.section_path, subpath], \"/\") : subpath;\n    const actorName =\n      kind === \"resolved\"\n        ? (resolvedActorName ?? parseEntityRef(actorRef).name)\n        : authorFromRow(row).name;\n    const [pageTitle, sectionTitle] = await Promise.all([\n      this.resolvePageTitle(row.site_ref, row.section_ref, subpath),\n      this.resolvePageTitle(row.site_ref, row.section_ref, \"\"),\n    ]);\n    await this.publish(kind, \"participants\", row, rootId, recipients, actorRef, {\n      entityRef: section?.entity_ref ?? null,\n      viewerPath,\n      actorName,\n      pageTitle,\n      sectionTitle,\n    });\n  }\n\n  private async publish(\n    kind: \"created\" | \"resolved\",\n    audience: CommentEventAudience,\n    row: CommentRow,\n    rootId: string,\n    recipients: string[],\n    actorRef: string,\n    link: {\n      entityRef: string | null;\n      viewerPath: string;\n      actorName: string;\n      pageTitle: string | null;\n      sectionTitle: string | null;\n    },\n  ): Promise<void> {\n    const eventPayload: CommentEventPayload = {\n      kind,\n      audience,\n      occurredAt: new Date().toISOString(),\n      commentId: row.id,\n      rootId,\n      parentId: row.parent_id,\n      siteRef: row.site_ref,\n      sectionRef: row.section_ref,\n      pageRef: row.page_ref,\n      actorRef,\n      recipients,\n      entityRef: link.entityRef,\n      // Anchor on the thread root, not the triggering row: a reply notification\n      // should open the whole thread (rootId === row.id for top-level + resolve events).\n      deepLinkSuffix: buildCommentDeepLinkSuffix({\n        viewerPath: link.viewerPath,\n        commentId: rootId,\n      }),\n      bodySnippet: snippetFromHtml(row.body_html),\n      actorName: link.actorName,\n      pageTitle: link.pageTitle,\n      sectionTitle: link.sectionTitle,\n    };\n    await this.events.publish({ topic: RW_COMMENTS_TOPIC, eventPayload });\n  }\n}\n"],"names":["subpathOf","joinNonEmpty","authorFromRow","parseEntityRef","buildCommentDeepLinkSuffix","snippetFromHtml","RW_COMMENTS_TOPIC"],"mappings":"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"}

package/dist/comments/CommentStore.cjs.js

@@ -0,0 +1,160 @@
+'use strict';
+
+var uuid = require('uuid');
+var core = require('@rwdocs/core');
+var types = require('./types.cjs.js');
+
+const TABLE = "comments";
+class CommentStore {
+  constructor(knex) {
+    this.knex = knex;
+  }
+  async create(siteRef, input) {
+    const now = /* @__PURE__ */ new Date();
+    const row = {
+      id: uuid.v7(),
+      site_ref: siteRef,
+      page_ref: input.pageRef,
+      section_ref: types.sectionRefOf(input.pageRef),
+      parent_id: input.parentId ?? null,
+      author_ref: input.authorRef,
+      author_profile: input.authorProfile ? JSON.stringify(input.authorProfile) : null,
+      body: input.body,
+      body_html: await core.renderCommentBody(input.body),
+      selectors: JSON.stringify(input.selectors),
+      status: "open",
+      created_at: now,
+      updated_at: now,
+      resolved_at: null,
+      resolved_by: null,
+      deleted_at: null
+    };
+    await this.knex(TABLE).insert(row);
+    return row;
+  }
+  /**
+   * By global uuid; includes soft-deleted rows.
+   *
+   * Pass `opts.executor` (a transaction) to read inside an open transaction, and
+   * `opts.forUpdate` to lock the row for the rest of the transaction (real
+   * `SELECT ... FOR UPDATE` on Postgres; ignored/no-op on better-sqlite3, whose
+   * transactions already serialize writes).
+   */
+  async get(id, opts) {
+    const q = (opts?.executor ?? this.knex)(TABLE).where({ id });
+    if (opts?.forUpdate) q.forUpdate();
+    return q.first();
+  }
+  /** Run `fn` inside a single database transaction. */
+  async transaction(fn) {
+    return this.knex.transaction(fn);
+  }
+  /**
+   * Site-scoped; ALWAYS excludes soft-deleted rows; ORDER BY created_at ASC.
+   *
+   * Forward hook: the router currently reads only by `pageRef`. The additional
+   * `ListFilter` fields (`sectionRef`, `status`, `parentId`, `topLevelOnly`) and the
+   * corresponding `section_ref` column + `comments_section_idx` index are intentional
+   * forward hooks for the planned cross-section / entity-scoped querying direction (v1
+   * design). They are not dead code.
+   */
+  async list(siteRef, filter) {
+    const q = this.knex(TABLE).where({ site_ref: siteRef }).whereNull("deleted_at");
+    if (filter.pageRef !== void 0) q.andWhere({ page_ref: filter.pageRef });
+    if (filter.sectionRef !== void 0) q.andWhere({ section_ref: filter.sectionRef });
+    if (filter.status !== void 0) q.andWhere({ status: filter.status });
+    if (filter.parentId !== void 0) q.andWhere({ parent_id: filter.parentId });
+    if (filter.topLevelOnly) q.whereNull("parent_id");
+    return q.orderBy("created_at", "asc").orderBy("id", "asc");
+  }
+  async update(id, patch) {
+    const existing = await this.get(id);
+    if (!existing) return void 0;
+    const now = /* @__PURE__ */ new Date();
+    const changes = { updated_at: now };
+    if (patch.body !== void 0) {
+      changes.body = patch.body;
+      changes.body_html = await core.renderCommentBody(patch.body);
+    }
+    if (patch.selectors !== void 0) {
+      changes.selectors = JSON.stringify(patch.selectors);
+    }
+    if (patch.status !== void 0) {
+      changes.status = patch.status;
+      if (patch.status === "resolved") {
+        changes.resolved_at = this.knex.raw("COALESCE(resolved_at, ?)", [now]);
+        changes.resolved_by = this.knex.raw("COALESCE(resolved_by, ?)", [
+          patch.resolverRef ?? null
+        ]);
+      } else {
+        changes.resolved_at = null;
+        changes.resolved_by = null;
+      }
+    }
+    await this.knex(TABLE).where({ id }).update(changes);
+    return this.get(id);
+  }
+  /**
+   * Conditional soft-delete: only applies to a currently-live row (`deleted_at IS
+   * NULL`). Returns the fresh row when it applied, or `undefined` when 0 rows
+   * matched (the row was already deleted — a lost race). Pass `executor` to run
+   * inside an open transaction.
+   */
+  async softDelete(id, executor) {
+    const db = executor ?? this.knex;
+    const now = /* @__PURE__ */ new Date();
+    const count = await db(TABLE).where({ id }).whereNull("deleted_at").update({ deleted_at: now, updated_at: now });
+    if (count === 0) return void 0;
+    return this.get(id, { executor });
+  }
+  /**
+   * Conditional restore: only applies to a currently-deleted row (`deleted_at IS
+   * NOT NULL`). Returns the fresh row when it applied, or `undefined` when 0 rows
+   * matched (the row was already live — a lost race). Pass `executor` to run
+   * inside an open transaction.
+   */
+  async restore(id, executor) {
+    const db = executor ?? this.knex;
+    const count = await db(TABLE).where({ id }).whereNotNull("deleted_at").update({ deleted_at: null, updated_at: /* @__PURE__ */ new Date() });
+    if (count === 0) return void 0;
+    return this.get(id, { executor });
+  }
+  /**
+   * Distinct author refs participating in a thread: the root comment plus its direct,
+   * non-deleted replies (threads are one level deep, so `rootId` is the parent of every
+   * reply). Used by the comment-event publisher to address commenter-side notifications.
+   * Order is stable (creation order) so notification recipient lists are deterministic.
+   */
+  async participantsOf(rootId) {
+    const rows = await this.knex(TABLE).where(function whereInThread() {
+      this.where("id", rootId).orWhere("parent_id", rootId);
+    }).whereNull("deleted_at").orderBy("created_at", "asc").orderBy("id", "asc").select("author_ref");
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const row of rows) {
+      const ref = row.author_ref;
+      if (!seen.has(ref)) {
+        seen.add(ref);
+        out.push(ref);
+      }
+    }
+    return out;
+  }
+  /**
+   * Returns a map from parent_id → open reply count for a given set of
+   * top-level comment ids. Uses a single grouped query (no N+1).
+   * Only counts open, non-deleted replies.
+   */
+  async replyCountsFor(parentIds) {
+    const map = /* @__PURE__ */ new Map();
+    if (!parentIds.length) return map;
+    const rows = await this.knex(TABLE).whereIn("parent_id", parentIds).andWhere("status", "open").whereNull("deleted_at").groupBy("parent_id").select("parent_id").count("id as cnt");
+    for (const row of rows) {
+      map.set(row.parent_id, Number(row.cnt));
+    }
+    return map;
+  }
+}
+
+exports.CommentStore = CommentStore;
+//# sourceMappingURL=CommentStore.cjs.js.map

package/dist/comments/CommentStore.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommentStore.cjs.js","sources":["../../src/comments/CommentStore.ts"],"sourcesContent":["import type { Knex } from \"knex\";\nimport { v7 as uuidv7 } from \"uuid\";\nimport { renderCommentBody } from \"@rwdocs/core\";\nimport { CommentRow, CommentStatus, CreateCommentInput, ListFilter, sectionRefOf } from \"./types\";\n\nconst TABLE = \"comments\";\n\nexport class CommentStore {\n  constructor(private readonly knex: Knex) {}\n\n  async create(siteRef: string, input: CreateCommentInput): Promise<CommentRow> {\n    const now = new Date();\n    const row: CommentRow = {\n      id: uuidv7(),\n      site_ref: siteRef,\n      page_ref: input.pageRef,\n      section_ref: sectionRefOf(input.pageRef),\n      parent_id: input.parentId ?? null,\n      author_ref: input.authorRef,\n      author_profile: input.authorProfile ? JSON.stringify(input.authorProfile) : null,\n      body: input.body,\n      body_html: await renderCommentBody(input.body),\n      selectors: JSON.stringify(input.selectors),\n      status: \"open\",\n      created_at: now,\n      updated_at: now,\n      resolved_at: null,\n      resolved_by: null,\n      deleted_at: null,\n    };\n    await this.knex(TABLE).insert(row);\n    return row;\n  }\n\n  /**\n   * By global uuid; includes soft-deleted rows.\n   *\n   * Pass `opts.executor` (a transaction) to read inside an open transaction, and\n   * `opts.forUpdate` to lock the row for the rest of the transaction (real\n   * `SELECT ... FOR UPDATE` on Postgres; ignored/no-op on better-sqlite3, whose\n   * transactions already serialize writes).\n   */\n  async get(\n    id: string,\n    opts?: { executor?: Knex.Transaction; forUpdate?: boolean },\n  ): Promise<CommentRow | undefined> {\n    const q = (opts?.executor ?? this.knex)<CommentRow>(TABLE).where({ id });\n    if (opts?.forUpdate) q.forUpdate();\n    return q.first();\n  }\n\n  /** Run `fn` inside a single database transaction. */\n  async transaction<T>(fn: (tx: Knex.Transaction) => Promise<T>): Promise<T> {\n    return this.knex.transaction(fn);\n  }\n\n  /**\n   * Site-scoped; ALWAYS excludes soft-deleted rows; ORDER BY created_at ASC.\n   *\n   * Forward hook: the router currently reads only by `pageRef`. The additional\n   * `ListFilter` fields (`sectionRef`, `status`, `parentId`, `topLevelOnly`) and the\n   * corresponding `section_ref` column + `comments_section_idx` index are intentional\n   * forward hooks for the planned cross-section / entity-scoped querying direction (v1\n   * design). They are not dead code.\n   */\n  async list(siteRef: string, filter: ListFilter): Promise<CommentRow[]> {\n    const q = this.knex<CommentRow>(TABLE).where({ site_ref: siteRef }).whereNull(\"deleted_at\");\n    if (filter.pageRef !== undefined) q.andWhere({ page_ref: filter.pageRef });\n    if (filter.sectionRef !== undefined) q.andWhere({ section_ref: filter.sectionRef });\n    if (filter.status !== undefined) q.andWhere({ status: filter.status });\n    if (filter.parentId !== undefined) q.andWhere({ parent_id: filter.parentId });\n    if (filter.topLevelOnly) q.whereNull(\"parent_id\");\n    return q.orderBy(\"created_at\", \"asc\").orderBy(\"id\", \"asc\");\n  }\n\n  async update(\n    id: string,\n    patch: { body?: string; status?: CommentStatus; selectors?: unknown[]; resolverRef?: string },\n  ): Promise<CommentRow | undefined> {\n    const existing = await this.get(id);\n    if (!existing) return undefined;\n\n    const now = new Date();\n    const changes: Partial<CommentRow> = { updated_at: now };\n    if (patch.body !== undefined) {\n      changes.body = patch.body;\n      changes.body_html = await renderCommentBody(patch.body);\n    }\n    if (patch.selectors !== undefined) {\n      changes.selectors = JSON.stringify(patch.selectors);\n    }\n    if (patch.status !== undefined) {\n      changes.status = patch.status;\n      if (patch.status === \"resolved\") {\n        // Push the idempotency guard into SQL — concurrent resolves can't double-stamp.\n        // COALESCE leaves existing stamps intact; works on both better-sqlite3 and Postgres.\n        (changes as any).resolved_at = this.knex.raw(\"COALESCE(resolved_at, ?)\", [now]);\n        (changes as any).resolved_by = this.knex.raw(\"COALESCE(resolved_by, ?)\", [\n          patch.resolverRef ?? null,\n        ]);\n      } else {\n        changes.resolved_at = null;\n        changes.resolved_by = null;\n      }\n    }\n    await this.knex(TABLE).where({ id }).update(changes);\n    return this.get(id);\n  }\n\n  /**\n   * Conditional soft-delete: only applies to a currently-live row (`deleted_at IS\n   * NULL`). Returns the fresh row when it applied, or `undefined` when 0 rows\n   * matched (the row was already deleted — a lost race). Pass `executor` to run\n   * inside an open transaction.\n   */\n  async softDelete(id: string, executor?: Knex.Transaction): Promise<CommentRow | undefined> {\n    const db = executor ?? this.knex;\n    const now = new Date();\n    const count = await db(TABLE)\n      .where({ id })\n      .whereNull(\"deleted_at\")\n      .update({ deleted_at: now, updated_at: now });\n    if (count === 0) return undefined;\n    return this.get(id, { executor });\n  }\n\n  /**\n   * Conditional restore: only applies to a currently-deleted row (`deleted_at IS\n   * NOT NULL`). Returns the fresh row when it applied, or `undefined` when 0 rows\n   * matched (the row was already live — a lost race). Pass `executor` to run\n   * inside an open transaction.\n   */\n  async restore(id: string, executor?: Knex.Transaction): Promise<CommentRow | undefined> {\n    const db = executor ?? this.knex;\n    const count = await db(TABLE)\n      .where({ id })\n      .whereNotNull(\"deleted_at\")\n      .update({ deleted_at: null, updated_at: new Date() });\n    if (count === 0) return undefined;\n    return this.get(id, { executor });\n  }\n\n  /**\n   * Distinct author refs participating in a thread: the root comment plus its direct,\n   * non-deleted replies (threads are one level deep, so `rootId` is the parent of every\n   * reply). Used by the comment-event publisher to address commenter-side notifications.\n   * Order is stable (creation order) so notification recipient lists are deterministic.\n   */\n  async participantsOf(rootId: string): Promise<string[]> {\n    const rows = await this.knex(TABLE)\n      .where(function whereInThread(this: Knex.QueryBuilder) {\n        this.where(\"id\", rootId).orWhere(\"parent_id\", rootId);\n      })\n      .whereNull(\"deleted_at\")\n      .orderBy(\"created_at\", \"asc\")\n      .orderBy(\"id\", \"asc\")\n      .select(\"author_ref\");\n    const seen = new Set<string>();\n    const out: string[] = [];\n    for (const row of rows) {\n      const ref = row.author_ref as string;\n      if (!seen.has(ref)) {\n        seen.add(ref);\n        out.push(ref);\n      }\n    }\n    return out;\n  }\n\n  /**\n   * Returns a map from parent_id → open reply count for a given set of\n   * top-level comment ids. Uses a single grouped query (no N+1).\n   * Only counts open, non-deleted replies.\n   */\n  async replyCountsFor(parentIds: string[]): Promise<Map<string, number>> {\n    const map = new Map<string, number>();\n    if (!parentIds.length) return map;\n    const rows = await this.knex(TABLE)\n      .whereIn(\"parent_id\", parentIds)\n      .andWhere(\"status\", \"open\")\n      .whereNull(\"deleted_at\")\n      .groupBy(\"parent_id\")\n      .select(\"parent_id\")\n      .count(\"id as cnt\");\n    for (const row of rows) {\n      map.set(row.parent_id as string, Number(row.cnt));\n    }\n    return map;\n  }\n}\n"],"names":["uuidv7","sectionRefOf","renderCommentBody"],"mappings":"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"}

package/dist/comments/author.cjs.js

@@ -0,0 +1,38 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+
+function authorFromRow(row) {
+  const profile = row.author_profile ? JSON.parse(row.author_profile) : null;
+  return {
+    id: row.author_ref,
+    name: profile?.displayName ?? catalogModel.parseEntityRef(row.author_ref).name,
+    ...profile?.picture ? { avatarUrl: profile.picture } : {}
+  };
+}
+async function resolveAuthor(deps) {
+  const { userInfo, auth, catalog, credentials } = deps;
+  const { userEntityRef } = await userInfo.getUserInfo(credentials);
+  const serviceCreds = await auth.getOwnServiceCredentials();
+  let entity;
+  try {
+    entity = await catalog.getEntityByRef(userEntityRef, { credentials: serviceCreds });
+  } catch {
+    return { authorRef: userEntityRef };
+  }
+  const profile = entity?.spec?.profile;
+  if (profile?.displayName || profile?.picture) {
+    return {
+      authorRef: userEntityRef,
+      authorProfile: {
+        ...profile.displayName ? { displayName: profile.displayName } : {},
+        ...profile.picture ? { picture: profile.picture } : {}
+      }
+    };
+  }
+  return { authorRef: userEntityRef };
+}
+
+exports.authorFromRow = authorFromRow;
+exports.resolveAuthor = resolveAuthor;
+//# sourceMappingURL=author.cjs.js.map

package/dist/comments/author.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"author.cjs.js","sources":["../../src/comments/author.ts"],"sourcesContent":["import type {\n  AuthService,\n  BackstageCredentials,\n  UserInfoService,\n} from \"@backstage/backend-plugin-api\";\nimport type { CatalogService } from \"@backstage/plugin-catalog-node\";\nimport { parseEntityRef } from \"@backstage/catalog-model\";\nimport { AuthorProfile, CommentRow } from \"./types\";\n\n/**\n * Shapes the display author ({ id, name, avatarUrl? }) from a comment row's\n * stored author_ref + author_profile snapshot. Shared by the thread view\n * (toCommentResponse) and the inbox (toInboxItem) so both render an author\n * identically; the name falls back to the humanized entity name when there's\n * no profile snapshot.\n */\nexport function authorFromRow(row: Pick<CommentRow, \"author_ref\" | \"author_profile\">): {\n  id: string;\n  name: string;\n  avatarUrl?: string;\n} {\n  const profile: AuthorProfile | null = row.author_profile ? JSON.parse(row.author_profile) : null;\n  return {\n    id: row.author_ref,\n    name: profile?.displayName ?? parseEntityRef(row.author_ref).name,\n    ...(profile?.picture ? { avatarUrl: profile.picture } : {}),\n  };\n}\n\nexport async function resolveAuthor(deps: {\n  userInfo: UserInfoService;\n  auth: AuthService;\n  catalog: CatalogService;\n  credentials: BackstageCredentials;\n}): Promise<{ authorRef: string; authorProfile?: AuthorProfile }> {\n  const { userInfo, auth, catalog, credentials } = deps;\n  const { userEntityRef } = await userInfo.getUserInfo(credentials);\n\n  const serviceCreds = await auth.getOwnServiceCredentials();\n  let entity: Awaited<ReturnType<typeof catalog.getEntityByRef>>;\n  try {\n    entity = await catalog.getEntityByRef(userEntityRef, { credentials: serviceCreds });\n  } catch {\n    return { authorRef: userEntityRef };\n  }\n\n  const profile = entity?.spec?.profile as { displayName?: string; picture?: string } | undefined;\n  if (profile?.displayName || profile?.picture) {\n    return {\n      authorRef: userEntityRef,\n      authorProfile: {\n        ...(profile.displayName ? { displayName: profile.displayName } : {}),\n        ...(profile.picture ? { picture: profile.picture } : {}),\n      },\n    };\n  }\n  return { authorRef: userEntityRef };\n}\n"],"names":["parseEntityRef"],"mappings":";;;;AAgBO,SAAS,cAAc,GAAA,EAI5B;AACA,EAAA,MAAM,UAAgC,GAAA,CAAI,cAAA,GAAiB,KAAK,KAAA,CAAM,GAAA,CAAI,cAAc,CAAA,GAAI,IAAA;AAC5F,EAAA,OAAO;AAAA,IACL,IAAI,GAAA,CAAI,UAAA;AAAA,IACR,MAAM,OAAA,EAAS,WAAA,IAAeA,2BAAA,CAAe,GAAA,CAAI,UAAU,CAAA,CAAE,IAAA;AAAA,IAC7D,GAAI,SAAS,OAAA,GAAU,EAAE,WAAW,OAAA,CAAQ,OAAA,KAAY;AAAC,GAC3D;AACF;AAEA,eAAsB,cAAc,IAAA,EAK8B;AAChE,EAAA,MAAM,EAAE,QAAA,EAAU,IAAA,EAAM,OAAA,EAAS,aAAY,GAAI,IAAA;AACjD,EAAA,MAAM,EAAE,aAAA,EAAc,GAAI,MAAM,QAAA,CAAS,YAAY,WAAW,CAAA;AAEhE,EAAA,MAAM,YAAA,GAAe,MAAM,IAAA,CAAK,wBAAA,EAAyB;AACzD,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,MAAM,OAAA,CAAQ,cAAA,CAAe,eAAe,EAAE,WAAA,EAAa,cAAc,CAAA;AAAA,EACpF,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAE,WAAW,aAAA,EAAc;AAAA,EACpC;AAEA,EAAA,MAAM,OAAA,GAAU,QAAQ,IAAA,EAAM,OAAA;AAC9B,EAAA,IAAI,OAAA,EAAS,WAAA,IAAe,OAAA,EAAS,OAAA,EAAS;AAC5C,IAAA,OAAO;AAAA,MACL,SAAA,EAAW,aAAA;AAAA,MACX,aAAA,EAAe;AAAA,QACb,GAAI,QAAQ,WAAA,GAAc,EAAE,aAAa,OAAA,CAAQ,WAAA,KAAgB,EAAC;AAAA,QAClE,GAAI,QAAQ,OAAA,GAAU,EAAE,SAAS,OAAA,CAAQ,OAAA,KAAY;AAAC;AACxD,KACF;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAW,aAAA,EAAc;AACpC;;;;;"}

package/dist/comments/logging.cjs.js

@@ -0,0 +1,50 @@
+'use strict';
+
+function logCommentOp(logger, event) {
+  switch (event.kind) {
+    case "mutation":
+      logger.info(`comment op ${event.op}`, {
+        op: event.op,
+        siteRef: event.siteRef,
+        commentId: event.commentId,
+        ...event.parentId ? { parentId: event.parentId } : {},
+        outcome: "ok"
+      });
+      return;
+    case "denied":
+      logger.warn(`comment op ${event.op} denied`, {
+        op: event.op,
+        permission: event.permission,
+        userEntityRef: event.userEntityRef,
+        outcome: "denied"
+      });
+      return;
+    case "entity-not-visible":
+      logger.warn(`comment op ${event.op} entity not visible`, {
+        op: event.op,
+        siteRef: event.siteRef,
+        userEntityRef: event.userEntityRef,
+        outcome: "entity-not-visible"
+      });
+      return;
+    case "oversized-list":
+      logger.warn("comment list oversized", {
+        op: "list",
+        siteRef: event.siteRef,
+        pageRef: event.pageRef,
+        count: event.count,
+        bytes: event.bytes
+      });
+      return;
+    case "error":
+      logger.error(`comment op ${event.op} failed`, {
+        op: event.op,
+        outcome: "error",
+        err: event.err instanceof Error ? event.err.message : String(event.err)
+      });
+      return;
+  }
+}
+
+exports.logCommentOp = logCommentOp;
+//# sourceMappingURL=logging.cjs.js.map

package/dist/comments/logging.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.cjs.js","sources":["../../src/comments/logging.ts"],"sourcesContent":["import type { LoggerService } from \"@backstage/backend-plugin-api\";\n\n/**\n * `mutation` and `denied` are the only variants emitted today. `entity-not-visible`,\n * `oversized-list`, and `error` are defined ahead of their emitters as intentional\n * forward hooks — the switch in `logCommentOp` already handles them so adding an\n * emitter later requires no structural change here.\n */\nexport type CommentLogEvent =\n  | { kind: \"mutation\"; op: string; siteRef: string; commentId: string; parentId?: string }\n  | { kind: \"denied\"; op: string; permission: string; userEntityRef: string }\n  | { kind: \"entity-not-visible\"; op: string; siteRef: string; userEntityRef: string }\n  | { kind: \"oversized-list\"; siteRef: string; pageRef: string; count: number; bytes: number }\n  | { kind: \"error\"; op: string; err: unknown };\n\n/** Single funnel for comment-op logging. PII (body/html/profile/selectors/tokens) is\n *  not representable in CommentLogEvent, so it cannot be logged here. */\nexport function logCommentOp(logger: LoggerService, event: CommentLogEvent): void {\n  switch (event.kind) {\n    case \"mutation\":\n      logger.info(`comment op ${event.op}`, {\n        op: event.op,\n        siteRef: event.siteRef,\n        commentId: event.commentId,\n        ...(event.parentId ? { parentId: event.parentId } : {}),\n        outcome: \"ok\",\n      });\n      return;\n    case \"denied\":\n      logger.warn(`comment op ${event.op} denied`, {\n        op: event.op,\n        permission: event.permission,\n        userEntityRef: event.userEntityRef,\n        outcome: \"denied\",\n      });\n      return;\n    case \"entity-not-visible\":\n      logger.warn(`comment op ${event.op} entity not visible`, {\n        op: event.op,\n        siteRef: event.siteRef,\n        userEntityRef: event.userEntityRef,\n        outcome: \"entity-not-visible\",\n      });\n      return;\n    case \"oversized-list\":\n      logger.warn(\"comment list oversized\", {\n        op: \"list\",\n        siteRef: event.siteRef,\n        pageRef: event.pageRef,\n        count: event.count,\n        bytes: event.bytes,\n      });\n      return;\n    case \"error\":\n      logger.error(`comment op ${event.op} failed`, {\n        op: event.op,\n        outcome: \"error\",\n        err: event.err instanceof Error ? event.err.message : String(event.err),\n      });\n      return;\n    default: {\n      // Exhaustiveness check — TypeScript ensures this is unreachable.\n      const _: never = event;\n      void _;\n    }\n  }\n}\n"],"names":[],"mappings":";;AAiBO,SAAS,YAAA,CAAa,QAAuB,KAAA,EAA8B;AAChF,EAAA,QAAQ,MAAM,IAAA;AAAM,IAClB,KAAK,UAAA;AACH,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,WAAA,EAAc,KAAA,CAAM,EAAE,CAAA,CAAA,EAAI;AAAA,QACpC,IAAI,KAAA,CAAM,EAAA;AAAA,QACV,SAAS,KAAA,CAAM,OAAA;AAAA,QACf,WAAW,KAAA,CAAM,SAAA;AAAA,QACjB,GAAI,MAAM,QAAA,GAAW,EAAE,UAAU,KAAA,CAAM,QAAA,KAAa,EAAC;AAAA,QACrD,OAAA,EAAS;AAAA,OACV,CAAA;AACD,MAAA;AAAA,IACF,KAAK,QAAA;AACH,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,WAAA,EAAc,KAAA,CAAM,EAAE,CAAA,OAAA,CAAA,EAAW;AAAA,QAC3C,IAAI,KAAA,CAAM,EAAA;AAAA,QACV,YAAY,KAAA,CAAM,UAAA;AAAA,QAClB,eAAe,KAAA,CAAM,aAAA;AAAA,QACrB,OAAA,EAAS;AAAA,OACV,CAAA;AACD,MAAA;AAAA,IACF,KAAK,oBAAA;AACH,MAAA,MAAA,CAAO,IAAA,CAAK,CAAA,WAAA,EAAc,KAAA,CAAM,EAAE,CAAA,mBAAA,CAAA,EAAuB;AAAA,QACvD,IAAI,KAAA,CAAM,EAAA;AAAA,QACV,SAAS,KAAA,CAAM,OAAA;AAAA,QACf,eAAe,KAAA,CAAM,aAAA;AAAA,QACrB,OAAA,EAAS;AAAA,OACV,CAAA;AACD,MAAA;AAAA,IACF,KAAK,gBAAA;AACH,MAAA,MAAA,CAAO,KAAK,wBAAA,EAA0B;AAAA,QACpC,EAAA,EAAI,MAAA;AAAA,QACJ,SAAS,KAAA,CAAM,OAAA;AAAA,QACf,SAAS,KAAA,CAAM,OAAA;AAAA,QACf,OAAO,KAAA,CAAM,KAAA;AAAA,QACb,OAAO,KAAA,CAAM;AAAA,OACd,CAAA;AACD,MAAA;AAAA,IACF,KAAK,OAAA;AACH,MAAA,MAAA,CAAO,KAAA,CAAM,CAAA,WAAA,EAAc,KAAA,CAAM,EAAE,CAAA,OAAA,CAAA,EAAW;AAAA,QAC5C,IAAI,KAAA,CAAM,EAAA;AAAA,QACV,OAAA,EAAS,OAAA;AAAA,QACT,GAAA,EAAK,MAAM,GAAA,YAAe,KAAA,GAAQ,MAAM,GAAA,CAAI,OAAA,GAAU,MAAA,CAAO,KAAA,CAAM,GAAG;AAAA,OACvE,CAAA;AACD,MAAA;AAKF;AAEJ;;;;"}

package/dist/comments/mapping.cjs.js

@@ -0,0 +1,32 @@
+'use strict';
+
+var timestamps = require('./timestamps.cjs.js');
+var author = require('./author.cjs.js');
+
+function toCommentResponse(row, callerRef) {
+  const isReply = row.parent_id !== null;
+  const deleted = row.deleted_at !== null;
+  const isAuthor = callerRef !== void 0 && callerRef === row.author_ref;
+  return {
+    id: row.id,
+    documentId: row.page_ref,
+    // viewer wire field — preserved until @rwdocs/viewer is updated
+    ...row.parent_id !== null ? { parentId: row.parent_id } : {},
+    author: author.authorFromRow(row),
+    body: row.body,
+    bodyHtml: row.body_html,
+    selectors: JSON.parse(row.selectors),
+    status: row.status,
+    createdAt: timestamps.toIso(row.created_at),
+    updatedAt: timestamps.toIso(row.updated_at),
+    ...deleted ? { deletedAt: timestamps.toIso(row.deleted_at) } : {},
+    canDelete: isReply && !deleted && isAuthor,
+    canRestore: deleted && isAuthor,
+    // Resolve is collaborative — any authenticated user may resolve/reopen a
+    // thread, unlike canDelete/canRestore which are author-only.
+    canResolve: !isReply && !deleted
+  };
+}
+
+exports.toCommentResponse = toCommentResponse;
+//# sourceMappingURL=mapping.cjs.js.map

package/dist/comments/mapping.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.cjs.js","sources":["../../src/comments/mapping.ts"],"sourcesContent":["import { CommentRow } from \"./types\";\nimport { toIso } from \"./timestamps\";\nimport { authorFromRow } from \"./author\";\n\nexport interface CommentResponse {\n  id: string;\n  documentId: string;\n  parentId?: string;\n  author: { id: string; name: string; avatarUrl?: string };\n  body: string;\n  bodyHtml: string;\n  selectors: unknown[];\n  status: \"open\" | \"resolved\";\n  createdAt: string;\n  updatedAt: string;\n  deletedAt?: string;\n  canDelete: boolean;\n  canRestore: boolean;\n  canResolve: boolean;\n}\n\nexport function toCommentResponse(row: CommentRow, callerRef: string | undefined): CommentResponse {\n  const isReply = row.parent_id !== null;\n  const deleted = row.deleted_at !== null;\n  const isAuthor = callerRef !== undefined && callerRef === row.author_ref;\n\n  return {\n    id: row.id,\n    documentId: row.page_ref, // viewer wire field — preserved until @rwdocs/viewer is updated\n    ...(row.parent_id !== null ? { parentId: row.parent_id } : {}),\n    author: authorFromRow(row),\n    body: row.body,\n    bodyHtml: row.body_html,\n    selectors: JSON.parse(row.selectors),\n    status: row.status,\n    createdAt: toIso(row.created_at)!,\n    updatedAt: toIso(row.updated_at)!,\n    ...(deleted ? { deletedAt: toIso(row.deleted_at) } : {}),\n    canDelete: isReply && !deleted && isAuthor,\n    canRestore: deleted && isAuthor,\n    // Resolve is collaborative — any authenticated user may resolve/reopen a\n    // thread, unlike canDelete/canRestore which are author-only.\n    canResolve: !isReply && !deleted,\n  };\n}\n"],"names":["authorFromRow","toIso"],"mappings":";;;;;AAqBO,SAAS,iBAAA,CAAkB,KAAiB,SAAA,EAAgD;AACjG,EAAA,MAAM,OAAA,GAAU,IAAI,SAAA,KAAc,IAAA;AAClC,EAAA,MAAM,OAAA,GAAU,IAAI,UAAA,KAAe,IAAA;AACnC,EAAA,MAAM,QAAA,GAAW,SAAA,KAAc,MAAA,IAAa,SAAA,KAAc,GAAA,CAAI,UAAA;AAE9D,EAAA,OAAO;AAAA,IACL,IAAI,GAAA,CAAI,EAAA;AAAA,IACR,YAAY,GAAA,CAAI,QAAA;AAAA;AAAA,IAChB,GAAI,IAAI,SAAA,KAAc,IAAA,GAAO,EAAE,QAAA,EAAU,GAAA,CAAI,SAAA,EAAU,GAAI,EAAC;AAAA,IAC5D,MAAA,EAAQA,qBAAc,GAAG,CAAA;AAAA,IACzB,MAAM,GAAA,CAAI,IAAA;AAAA,IACV,UAAU,GAAA,CAAI,SAAA;AAAA,IACd,SAAA,EAAW,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,SAAS,CAAA;AAAA,IACnC,QAAQ,GAAA,CAAI,MAAA;AAAA,IACZ,SAAA,EAAWC,gBAAA,CAAM,GAAA,CAAI,UAAU,CAAA;AAAA,IAC/B,SAAA,EAAWA,gBAAA,CAAM,GAAA,CAAI,UAAU,CAAA;AAAA,IAC/B,GAAI,UAAU,EAAE,SAAA,EAAWA,iBAAM,GAAA,CAAI,UAAU,CAAA,EAAE,GAAI,EAAC;AAAA,IACtD,SAAA,EAAW,OAAA,IAAW,CAAC,OAAA,IAAW,QAAA;AAAA,IAClC,YAAY,OAAA,IAAW,QAAA;AAAA;AAAA;AAAA,IAGvB,UAAA,EAAY,CAAC,OAAA,IAAW,CAAC;AAAA,GAC3B;AACF;;;;"}

package/dist/comments/permissions.cjs.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var v3 = require('zod/v3');
+var pluginPermissionNode = require('@backstage/plugin-permission-node');
+var backstagePluginRwCommon = require('@rwdocs/backstage-plugin-rw-common');
+
+const commentResourceRef = pluginPermissionNode.createPermissionResourceRef().with({
+  pluginId: "rw",
+  resourceType: backstagePluginRwCommon.RESOURCE_TYPE_RW_COMMENT
+});
+const isCommentAuthor = pluginPermissionNode.createPermissionRule(
+  {
+    name: "IS_COMMENT_AUTHOR",
+    description: "Allow only the comment author",
+    resourceRef: commentResourceRef,
+    paramsSchema: v3.z.object({ userRef: v3.z.string() }),
+    apply: (comment, { userRef }) => comment.author.id === userRef,
+    toQuery: () => ({})
+  }
+);
+
+exports.commentResourceRef = commentResourceRef;
+exports.isCommentAuthor = isCommentAuthor;
+//# sourceMappingURL=permissions.cjs.js.map

package/dist/comments/permissions.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.cjs.js","sources":["../../src/comments/permissions.ts"],"sourcesContent":["import { z } from \"zod/v3\";\nimport {\n  createPermissionResourceRef,\n  createPermissionRule,\n} from \"@backstage/plugin-permission-node\";\nimport { RESOURCE_TYPE_RW_COMMENT } from \"@rwdocs/backstage-plugin-rw-common\";\nimport type { CommentResponse } from \"./mapping\";\n\n/**\n * Resource ref for RW comments. TQuery is {} because all authorization\n * is applied in-memory (no DB query translation is needed).\n */\nexport const commentResourceRef = createPermissionResourceRef<CommentResponse, {}>().with({\n  pluginId: \"rw\",\n  resourceType: RESOURCE_TYPE_RW_COMMENT,\n});\n\n/**\n * Permission rule that returns true when the caller's userRef matches the comment author.\n * The caller ref is passed as a `userRef` param for testability.\n */\nexport const isCommentAuthor = createPermissionRule<typeof commentResourceRef, { userRef: string }>(\n  {\n    name: \"IS_COMMENT_AUTHOR\",\n    description: \"Allow only the comment author\",\n    resourceRef: commentResourceRef,\n    paramsSchema: z.object({ userRef: z.string() }),\n    apply: (comment, { userRef }) => comment.author.id === userRef,\n    toQuery: () => ({}),\n  },\n);\n"],"names":["createPermissionResourceRef","RESOURCE_TYPE_RW_COMMENT","createPermissionRule","z"],"mappings":";;;;;;AAYO,MAAM,kBAAA,GAAqBA,gDAAA,EAAiD,CAAE,IAAA,CAAK;AAAA,EACxF,QAAA,EAAU,IAAA;AAAA,EACV,YAAA,EAAcC;AAChB,CAAC;AAMM,MAAM,eAAA,GAAkBC,yCAAA;AAAA,EAC7B;AAAA,IACE,IAAA,EAAM,mBAAA;AAAA,IACN,WAAA,EAAa,+BAAA;AAAA,IACb,WAAA,EAAa,kBAAA;AAAA,IACb,YAAA,EAAcC,KAAE,MAAA,CAAO,EAAE,SAASA,IAAA,CAAE,MAAA,IAAU,CAAA;AAAA,IAC9C,KAAA,EAAO,CAAC,OAAA,EAAS,EAAE,SAAQ,KAAM,OAAA,CAAQ,OAAO,EAAA,KAAO,OAAA;AAAA,IACvD,OAAA,EAAS,OAAO,EAAC;AAAA;AAErB;;;;;"}