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

package/dist/siteIndex/SectionsReader.cjs.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const TABLE = "sections";
+class SectionsReader {
+  constructor(knex) {
+    this.knex = knex;
+  }
+  async getSection(siteRef, sectionRef) {
+    return this.knex(TABLE).where({ site_ref: siteRef, section_ref: sectionRef }).first();
+  }
+}
+
+exports.SectionsReader = SectionsReader;
+//# sourceMappingURL=SectionsReader.cjs.js.map

package/dist/siteIndex/SectionsReader.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SectionsReader.cjs.js","sources":["../../src/siteIndex/SectionsReader.ts"],"sourcesContent":["import type { Knex } from \"knex\";\nimport { SectionRow } from \"./types\";\n\nconst TABLE = \"sections\";\n\n/** By-key reader for the dense `sections` registry. Used by the comment-event publisher\n *  to resolve a section's effective owner (`entity_owner_ref`), its owning entity\n *  (`entity_ref`), and its owner-relative `section_path` for the deep link. One indexed\n *  point-read on PK (site_ref, section_ref); no RwSite load. Kept separate from the\n *  swap-only RegistryStore and the by-owner InboxStore reads. */\nexport class SectionsReader {\n  constructor(private readonly knex: Knex) {}\n\n  async getSection(siteRef: string, sectionRef: string): Promise<SectionRow | undefined> {\n    return this.knex<SectionRow>(TABLE)\n      .where({ site_ref: siteRef, section_ref: sectionRef })\n      .first();\n  }\n}\n"],"names":[],"mappings":";;AAGA,MAAM,KAAA,GAAQ,UAAA;AAOP,MAAM,cAAA,CAAe;AAAA,EAC1B,YAA6B,IAAA,EAAY;AAAZ,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAAa;AAAA,EAE1C,MAAM,UAAA,CAAW,OAAA,EAAiB,UAAA,EAAqD;AACrF,IAAA,OAAO,IAAA,CAAK,IAAA,CAAiB,KAAK,CAAA,CAC/B,KAAA,CAAM,EAAE,QAAA,EAAU,OAAA,EAAS,WAAA,EAAa,UAAA,EAAY,CAAA,CACpD,KAAA,EAAM;AAAA,EACX;AACF;;;;"}

package/dist/siteIndex/SiteRefreshStore.cjs.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const TABLE = "site_refresh";
+const LOCKING_CLIENTS = ["pg", "mysql", "mysql2"];
+class SiteRefreshStore {
+  constructor(knex) {
+    this.knex = knex;
+    this.useLocking = LOCKING_CLIENTS.includes(String(knex.client.config.client));
+  }
+  useLocking;
+  /** Insert a new queue row (due now) or, on conflict, only advance last_discovery_at. */
+  async upsertSite(siteRef, scanStart, executor) {
+    const exec = executor ?? this.knex;
+    await exec(TABLE).insert({
+      site_ref: siteRef,
+      next_update_at: scanStart,
+      last_built_at: null,
+      result_hash: null,
+      errors: null,
+      last_discovery_at: scanStart
+    }).onConflict("site_ref").merge(["last_discovery_at"]);
+  }
+  /** Delete queue rows not seen in the current (completed) scan. Returns count. */
+  async pruneMissing(scanStart) {
+    return this.knex(TABLE).where("last_discovery_at", "<", scanStart).del();
+  }
+  /** Claim up to `batch` due rows, bumping their lease, in one transaction. */
+  async claimDue(now, batch, leaseUntil) {
+    return this.knex.transaction(async (tx) => {
+      const q = tx(TABLE).where("next_update_at", "<=", now).orderBy("next_update_at", "asc").limit(batch).select("site_ref", "result_hash");
+      if (this.useLocking) q.forUpdate().skipLocked();
+      const rows = await q;
+      if (rows.length) {
+        await tx(TABLE).whereIn(
+          "site_ref",
+          rows.map((r) => r.site_ref)
+        ).update({ next_update_at: leaseUntil });
+      }
+      return rows.map((r) => ({ siteRef: r.site_ref, resultHash: r.result_hash ?? null }));
+    });
+  }
+  async completeSuccess(siteRef, resultHash, nextUpdateAt, now) {
+    await this.knex(TABLE).where({ site_ref: siteRef }).update({
+      last_built_at: now,
+      result_hash: resultHash,
+      errors: null,
+      next_update_at: nextUpdateAt
+    });
+  }
+  async recordError(siteRef, message) {
+    await this.knex(TABLE).where({ site_ref: siteRef }).update({ errors: message });
+  }
+  /** True iff every queue row has been built at least once. Returns true for an empty table
+   *  (vacuous truth) — prefer anyBuilt() to test readiness. */
+  async allBuilt() {
+    const [{ count }] = await this.knex(TABLE).whereNull("last_built_at").count({ count: "*" });
+    return Number(count) === 0;
+  }
+  /** True iff at least one queue row has been built. Preferred over allBuilt() for the inbox
+   *  readiness check: avoids (a) empty-table false-positive and (b) one permanently-failing site
+   *  blocking the inbox for all users forever. */
+  async anyBuilt() {
+    const [{ count }] = await this.knex(TABLE).whereNotNull("last_built_at").count({ count: "*" });
+    return Number(count) > 0;
+  }
+  /** Run fn in a single DB transaction (lets a caller atomically span multiple stores). */
+  async transaction(fn) {
+    return this.knex.transaction(fn);
+  }
+}
+
+exports.SiteRefreshStore = SiteRefreshStore;
+//# sourceMappingURL=SiteRefreshStore.cjs.js.map

package/dist/siteIndex/SiteRefreshStore.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SiteRefreshStore.cjs.js","sources":["../../src/siteIndex/SiteRefreshStore.ts"],"sourcesContent":["import type { Knex } from \"knex\";\nimport type { ClaimedSite } from \"./types\";\n\nconst TABLE = \"site_refresh\";\n// SQLite does not implement FOR UPDATE SKIP LOCKED; only take row locks on clients that support it.\nconst LOCKING_CLIENTS = [\"pg\", \"mysql\", \"mysql2\"];\n\nexport class SiteRefreshStore {\n  private readonly useLocking: boolean;\n  constructor(private readonly knex: Knex) {\n    this.useLocking = LOCKING_CLIENTS.includes(String(knex.client.config.client));\n  }\n\n  /** Insert a new queue row (due now) or, on conflict, only advance last_discovery_at. */\n  async upsertSite(\n    siteRef: string,\n    scanStart: Date,\n    executor?: Knex | Knex.Transaction,\n  ): Promise<void> {\n    const exec = executor ?? this.knex;\n    await exec(TABLE)\n      .insert({\n        site_ref: siteRef,\n        next_update_at: scanStart,\n        last_built_at: null,\n        result_hash: null,\n        errors: null,\n        last_discovery_at: scanStart,\n      })\n      .onConflict(\"site_ref\")\n      .merge([\"last_discovery_at\"]);\n  }\n\n  /** Delete queue rows not seen in the current (completed) scan. Returns count. */\n  async pruneMissing(scanStart: Date): Promise<number> {\n    return this.knex(TABLE).where(\"last_discovery_at\", \"<\", scanStart).del();\n  }\n\n  /** Claim up to `batch` due rows, bumping their lease, in one transaction. */\n  async claimDue(now: Date, batch: number, leaseUntil: Date): Promise<ClaimedSite[]> {\n    return this.knex.transaction(async (tx) => {\n      const q = tx(TABLE)\n        .where(\"next_update_at\", \"<=\", now)\n        .orderBy(\"next_update_at\", \"asc\")\n        .limit(batch)\n        .select(\"site_ref\", \"result_hash\");\n      if (this.useLocking) q.forUpdate().skipLocked();\n      const rows = await q;\n      if (rows.length) {\n        await tx(TABLE)\n          .whereIn(\n            \"site_ref\",\n            rows.map((r) => r.site_ref),\n          )\n          .update({ next_update_at: leaseUntil });\n      }\n      return rows.map((r) => ({ siteRef: r.site_ref, resultHash: r.result_hash ?? null }));\n    });\n  }\n\n  async completeSuccess(\n    siteRef: string,\n    resultHash: string,\n    nextUpdateAt: Date,\n    now: Date,\n  ): Promise<void> {\n    await this.knex(TABLE).where({ site_ref: siteRef }).update({\n      last_built_at: now,\n      result_hash: resultHash,\n      errors: null,\n      next_update_at: nextUpdateAt,\n    });\n  }\n\n  async recordError(siteRef: string, message: string): Promise<void> {\n    await this.knex(TABLE).where({ site_ref: siteRef }).update({ errors: message });\n  }\n\n  /** True iff every queue row has been built at least once. Returns true for an empty table\n   *  (vacuous truth) — prefer anyBuilt() to test readiness. */\n  async allBuilt(): Promise<boolean> {\n    const [{ count }] = await this.knex(TABLE).whereNull(\"last_built_at\").count({ count: \"*\" });\n    return Number(count) === 0;\n  }\n\n  /** True iff at least one queue row has been built. Preferred over allBuilt() for the inbox\n   *  readiness check: avoids (a) empty-table false-positive and (b) one permanently-failing site\n   *  blocking the inbox for all users forever. */\n  async anyBuilt(): Promise<boolean> {\n    const [{ count }] = await this.knex(TABLE).whereNotNull(\"last_built_at\").count({ count: \"*\" });\n    return Number(count) > 0;\n  }\n\n  /** Run fn in a single DB transaction (lets a caller atomically span multiple stores). */\n  async transaction<T>(fn: (tx: Knex.Transaction) => Promise<T>): Promise<T> {\n    return this.knex.transaction(fn);\n  }\n}\n"],"names":[],"mappings":";;AAGA,MAAM,KAAA,GAAQ,cAAA;AAEd,MAAM,eAAA,GAAkB,CAAC,IAAA,EAAM,OAAA,EAAS,QAAQ,CAAA;AAEzC,MAAM,gBAAA,CAAiB;AAAA,EAE5B,YAA6B,IAAA,EAAY;AAAZ,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAC3B,IAAA,IAAA,CAAK,UAAA,GAAa,gBAAgB,QAAA,CAAS,MAAA,CAAO,KAAK,MAAA,CAAO,MAAA,CAAO,MAAM,CAAC,CAAA;AAAA,EAC9E;AAAA,EAHiB,UAAA;AAAA;AAAA,EAMjB,MAAM,UAAA,CACJ,OAAA,EACA,SAAA,EACA,QAAA,EACe;AACf,IAAA,MAAM,IAAA,GAAO,YAAY,IAAA,CAAK,IAAA;AAC9B,IAAA,MAAM,IAAA,CAAK,KAAK,CAAA,CACb,MAAA,CAAO;AAAA,MACN,QAAA,EAAU,OAAA;AAAA,MACV,cAAA,EAAgB,SAAA;AAAA,MAChB,aAAA,EAAe,IAAA;AAAA,MACf,WAAA,EAAa,IAAA;AAAA,MACb,MAAA,EAAQ,IAAA;AAAA,MACR,iBAAA,EAAmB;AAAA,KACpB,EACA,UAAA,CAAW,UAAU,EACrB,KAAA,CAAM,CAAC,mBAAmB,CAAC,CAAA;AAAA,EAChC;AAAA;AAAA,EAGA,MAAM,aAAa,SAAA,EAAkC;AACnD,IAAA,OAAO,IAAA,CAAK,KAAK,KAAK,CAAA,CAAE,MAAM,mBAAA,EAAqB,GAAA,EAAK,SAAS,CAAA,CAAE,GAAA,EAAI;AAAA,EACzE;AAAA;AAAA,EAGA,MAAM,QAAA,CAAS,GAAA,EAAW,KAAA,EAAe,UAAA,EAA0C;AACjF,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,WAAA,CAAY,OAAO,EAAA,KAAO;AACzC,MAAA,MAAM,IAAI,EAAA,CAAG,KAAK,EACf,KAAA,CAAM,gBAAA,EAAkB,MAAM,GAAG,CAAA,CACjC,OAAA,CAAQ,gBAAA,EAAkB,KAAK,CAAA,CAC/B,KAAA,CAAM,KAAK,CAAA,CACX,MAAA,CAAO,YAAY,aAAa,CAAA;AACnC,MAAA,IAAI,IAAA,CAAK,UAAA,EAAY,CAAA,CAAE,SAAA,GAAY,UAAA,EAAW;AAC9C,MAAA,MAAM,OAAO,MAAM,CAAA;AACnB,MAAA,IAAI,KAAK,MAAA,EAAQ;AACf,QAAA,MAAM,EAAA,CAAG,KAAK,CAAA,CACX,OAAA;AAAA,UACC,UAAA;AAAA,UACA,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,KAAM,EAAE,QAAQ;AAAA,SAC5B,CACC,MAAA,CAAO,EAAE,cAAA,EAAgB,YAAY,CAAA;AAAA,MAC1C;AACA,MAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAC,CAAA,MAAO,EAAE,OAAA,EAAS,CAAA,CAAE,QAAA,EAAU,UAAA,EAAY,CAAA,CAAE,WAAA,IAAe,IAAA,EAAK,CAAE,CAAA;AAAA,IACrF,CAAC,CAAA;AAAA,EACH;AAAA,EAEA,MAAM,eAAA,CACJ,OAAA,EACA,UAAA,EACA,cACA,GAAA,EACe;AACf,IAAA,MAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA,CAAE,KAAA,CAAM,EAAE,QAAA,EAAU,OAAA,EAAS,CAAA,CAAE,MAAA,CAAO;AAAA,MACzD,aAAA,EAAe,GAAA;AAAA,MACf,WAAA,EAAa,UAAA;AAAA,MACb,MAAA,EAAQ,IAAA;AAAA,MACR,cAAA,EAAgB;AAAA,KACjB,CAAA;AAAA,EACH;AAAA,EAEA,MAAM,WAAA,CAAY,OAAA,EAAiB,OAAA,EAAgC;AACjE,IAAA,MAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA,CAAE,MAAM,EAAE,QAAA,EAAU,OAAA,EAAS,CAAA,CAAE,MAAA,CAAO,EAAE,MAAA,EAAQ,SAAS,CAAA;AAAA,EAChF;AAAA;AAAA;AAAA,EAIA,MAAM,QAAA,GAA6B;AACjC,IAAA,MAAM,CAAC,EAAE,KAAA,EAAO,CAAA,GAAI,MAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA,CAAE,UAAU,eAAe,CAAA,CAAE,MAAM,EAAE,KAAA,EAAO,KAAK,CAAA;AAC1F,IAAA,OAAO,MAAA,CAAO,KAAK,CAAA,KAAM,CAAA;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,QAAA,GAA6B;AACjC,IAAA,MAAM,CAAC,EAAE,KAAA,EAAO,CAAA,GAAI,MAAM,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA,CAAE,aAAa,eAAe,CAAA,CAAE,MAAM,EAAE,KAAA,EAAO,KAAK,CAAA;AAC7F,IAAA,OAAO,MAAA,CAAO,KAAK,CAAA,GAAI,CAAA;AAAA,EACzB;AAAA;AAAA,EAGA,MAAM,YAAe,EAAA,EAAsD;AACzE,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,WAAA,CAAY,EAAE,CAAA;AAAA,EACjC;AACF;;;;"}

package/dist/siteIndex/effectiveOwnership.cjs.js

@@ -0,0 +1,34 @@
+'use strict';
+
+function computeSectionRows(siteRef, sections, claims) {
+  const sentinel = claims.find((c) => c.section_ref === siteRef);
+  const realClaims = new Map(
+    claims.filter((c) => c.section_ref !== siteRef).map((c) => [c.section_ref, c])
+  );
+  const pathByRef = new Map(sections.map((s) => [s.sectionRef, s.path]));
+  const siteOwnerRef = sentinel?.entity_owner_ref ?? null;
+  return sections.map((s) => {
+    const claimerRef = [s.sectionRef, ...s.ancestors].find((ref) => realClaims.has(ref));
+    const claim = claimerRef ? realClaims.get(claimerRef) : null;
+    const entity_ref = claim?.entity_ref ?? siteRef;
+    const entity_owner_ref = claim ? claim.entity_owner_ref : siteOwnerRef;
+    const claimerPath = claimerRef ? pathByRef.get(claimerRef) ?? "" : "";
+    return {
+      site_ref: siteRef,
+      section_ref: s.sectionRef,
+      section_path: stripPrefix(s.path, claimerPath),
+      parent_section_ref: s.ancestors[0] ?? null,
+      // ancestors is nearest-first; [0] is immediate parent
+      entity_ref,
+      entity_owner_ref
+    };
+  });
+}
+function stripPrefix(full, prefix) {
+  if (!prefix) return full;
+  if (full === prefix) return "";
+  return full.startsWith(`${prefix}/`) ? full.slice(prefix.length + 1) : full;
+}
+
+exports.computeSectionRows = computeSectionRows;
+//# sourceMappingURL=effectiveOwnership.cjs.js.map

package/dist/siteIndex/effectiveOwnership.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effectiveOwnership.cjs.js","sources":["../../src/siteIndex/effectiveOwnership.ts"],"sourcesContent":["import type { SectionOwnershipRow, SectionRow } from \"./types\";\n\nexport interface RawSection {\n  sectionRef: string;\n  path: string;\n  ancestors: string[]; // nearest-first\n}\n\n/** Build the dense `sections` registry: one row per section carrying both structure\n *  (parent_section_ref) and effective ownership. A section is attributed to its nearest claiming\n *  ancestor (incl. itself), else the site-root sentinel (section_ref === siteRef), else a\n *  null-owner site fallback. The claimer's path is stripped so descendant paths become relative\n *  to the owning entity's docs root. */\nexport function computeSectionRows(\n  siteRef: string,\n  sections: RawSection[],\n  claims: SectionOwnershipRow[],\n): SectionRow[] {\n  const sentinel = claims.find((c) => c.section_ref === siteRef);\n  // Sentinel excluded from realClaims so it doesn't shadow per-section claims;\n  // its owner is only the fallback for sections with no more-specific claim.\n  const realClaims = new Map(\n    claims.filter((c) => c.section_ref !== siteRef).map((c) => [c.section_ref, c]),\n  );\n  const pathByRef = new Map(sections.map((s) => [s.sectionRef, s.path]));\n  const siteOwnerRef = sentinel?.entity_owner_ref ?? null;\n\n  return sections.map((s) => {\n    const claimerRef = [s.sectionRef, ...s.ancestors].find((ref) => realClaims.has(ref));\n    const claim = claimerRef ? realClaims.get(claimerRef)! : null;\n    const entity_ref = claim?.entity_ref ?? siteRef;\n    const entity_owner_ref = claim ? claim.entity_owner_ref : siteOwnerRef;\n    const claimerPath = claimerRef ? (pathByRef.get(claimerRef) ?? \"\") : \"\";\n    return {\n      site_ref: siteRef,\n      section_ref: s.sectionRef,\n      section_path: stripPrefix(s.path, claimerPath),\n      parent_section_ref: s.ancestors[0] ?? null, // ancestors is nearest-first; [0] is immediate parent\n      entity_ref,\n      entity_owner_ref,\n    };\n  });\n}\n\nfunction stripPrefix(full: string, prefix: string): string {\n  if (!prefix) return full;\n  if (full === prefix) return \"\";\n  return full.startsWith(`${prefix}/`) ? full.slice(prefix.length + 1) : full;\n}\n"],"names":[],"mappings":";;AAaO,SAAS,kBAAA,CACd,OAAA,EACA,QAAA,EACA,MAAA,EACc;AACd,EAAA,MAAM,WAAW,MAAA,CAAO,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,gBAAgB,OAAO,CAAA;AAG7D,EAAA,MAAM,aAAa,IAAI,GAAA;AAAA,IACrB,MAAA,CAAO,MAAA,CAAO,CAAC,CAAA,KAAM,EAAE,WAAA,KAAgB,OAAO,CAAA,CAAE,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,WAAA,EAAa,CAAC,CAAC;AAAA,GAC/E;AACA,EAAA,MAAM,SAAA,GAAY,IAAI,GAAA,CAAI,QAAA,CAAS,GAAA,CAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,UAAA,EAAY,CAAA,CAAE,IAAI,CAAC,CAAC,CAAA;AACrE,EAAA,MAAM,YAAA,GAAe,UAAU,gBAAA,IAAoB,IAAA;AAEnD,EAAA,OAAO,QAAA,CAAS,GAAA,CAAI,CAAC,CAAA,KAAM;AACzB,IAAA,MAAM,UAAA,GAAa,CAAC,CAAA,CAAE,UAAA,EAAY,GAAG,CAAA,CAAE,SAAS,CAAA,CAAE,IAAA,CAAK,CAAC,GAAA,KAAQ,UAAA,CAAW,GAAA,CAAI,GAAG,CAAC,CAAA;AACnF,IAAA,MAAM,KAAA,GAAQ,UAAA,GAAa,UAAA,CAAW,GAAA,CAAI,UAAU,CAAA,GAAK,IAAA;AACzD,IAAA,MAAM,UAAA,GAAa,OAAO,UAAA,IAAc,OAAA;AACxC,IAAA,MAAM,gBAAA,GAAmB,KAAA,GAAQ,KAAA,CAAM,gBAAA,GAAmB,YAAA;AAC1D,IAAA,MAAM,cAAc,UAAA,GAAc,SAAA,CAAU,GAAA,CAAI,UAAU,KAAK,EAAA,GAAM,EAAA;AACrE,IAAA,OAAO;AAAA,MACL,QAAA,EAAU,OAAA;AAAA,MACV,aAAa,CAAA,CAAE,UAAA;AAAA,MACf,YAAA,EAAc,WAAA,CAAY,CAAA,CAAE,IAAA,EAAM,WAAW,CAAA;AAAA,MAC7C,kBAAA,EAAoB,CAAA,CAAE,SAAA,CAAU,CAAC,CAAA,IAAK,IAAA;AAAA;AAAA,MACtC,UAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF,CAAC,CAAA;AACH;AAEA,SAAS,WAAA,CAAY,MAAc,MAAA,EAAwB;AACzD,EAAA,IAAI,CAAC,QAAQ,OAAO,IAAA;AACpB,EAAA,IAAI,IAAA,KAAS,QAAQ,OAAO,EAAA;AAC5B,EAAA,OAAO,IAAA,CAAK,UAAA,CAAW,CAAA,EAAG,MAAM,CAAA,CAAA,CAAG,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,MAAA,GAAS,CAAC,CAAA,GAAI,IAAA;AACzE;;;;"}

package/dist/siteIndex/registryHash.cjs.js

@@ -0,0 +1,10 @@
+'use strict';
+
+var crypto = require('crypto');
+
+function registryHash(sections, pages) {
+  return crypto.createHash("sha256").update(JSON.stringify({ sections, pages })).digest("hex");
+}
+
+exports.registryHash = registryHash;
+//# sourceMappingURL=registryHash.cjs.js.map

package/dist/siteIndex/registryHash.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registryHash.cjs.js","sources":["../../src/siteIndex/registryHash.ts"],"sourcesContent":["import { createHash } from \"crypto\";\nimport type { SectionRow, PageRow } from \"./types\";\n\n/** Deterministic hash of a site's registries. Both arrays (sections, pages) must be pre-sorted by\n *  the caller: JSON.stringify is order-sensitive. `sections` carries effective ownership, so an\n *  ownership change flips the hash and triggers a re-swap. */\nexport function registryHash(sections: SectionRow[], pages: PageRow[]): string {\n  return createHash(\"sha256\").update(JSON.stringify({ sections, pages })).digest(\"hex\");\n}\n"],"names":["createHash"],"mappings":";;;;AAMO,SAAS,YAAA,CAAa,UAAwB,KAAA,EAA0B;AAC7E,EAAA,OAAOA,iBAAA,CAAW,QAAQ,CAAA,CAAE,MAAA,CAAO,IAAA,CAAK,SAAA,CAAU,EAAE,QAAA,EAAU,KAAA,EAAO,CAAC,CAAA,CAAE,OAAO,KAAK,CAAA;AACtF;;;;"}

package/dist/siteIndex/runScan.cjs.js

@@ -0,0 +1,75 @@
+'use strict';
+
+var catalogModel = require('@backstage/catalog-model');
+var backstagePluginRwCommon = require('@rwdocs/backstage-plugin-rw-common');
+
+function ownerOf(entity) {
+  const rel = (entity.relations ?? []).find((r) => r.type === catalogModel.RELATION_OWNED_BY);
+  return rel?.targetRef ?? null;
+}
+async function runScan(deps) {
+  const { catalog, auth, logger, siteConfig, sectionOwnershipStore, siteRefreshStore } = deps;
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const credentials = await auth.getOwnServiceCredentials();
+  const onlySiteRef = siteConfig.projectDir && siteConfig.entity ? catalogModel.stringifyEntityRef(catalogModel.parseEntityRef(siteConfig.entity)) : void 0;
+  const scanStart = now();
+  const linksBySite = /* @__PURE__ */ new Map();
+  let completed = false;
+  let writeFailed = false;
+  try {
+    for await (const { entity } of backstagePluginRwCommon.iterateAnnotatedEntities(catalog, credentials)) {
+      const selfRef = catalogModel.stringifyEntityRef(catalogModel.getCompoundEntityRef(entity));
+      const parsed = backstagePluginRwCommon.parseAnnotation(
+        entity.metadata?.annotations?.[backstagePluginRwCommon.RW_ANNOTATION],
+        backstagePluginRwCommon.toEntityPath(selfRef)
+      );
+      if (!parsed) continue;
+      const siteRef = parsed.entityRef;
+      if (onlySiteRef && siteRef !== onlySiteRef) continue;
+      let link;
+      if (parsed.sectionRef) {
+        link = {
+          site_ref: siteRef,
+          section_ref: parsed.sectionRef,
+          entity_ref: selfRef,
+          entity_owner_ref: ownerOf(entity)
+        };
+      } else if (parsed.entityRef === selfRef) {
+        link = {
+          site_ref: siteRef,
+          section_ref: siteRef,
+          entity_ref: selfRef,
+          entity_owner_ref: ownerOf(entity)
+        };
+      }
+      if (!link) continue;
+      const inner = linksBySite.get(siteRef) ?? /* @__PURE__ */ new Map();
+      inner.set(link.section_ref, link);
+      linksBySite.set(siteRef, inner);
+    }
+    completed = true;
+  } catch (err) {
+    logger.warn(`Site index scan iteration failed; skipping prune: ${err}`);
+  }
+  for (const [siteRef, inner] of linksBySite) {
+    try {
+      await siteRefreshStore.transaction(async (tx) => {
+        await sectionOwnershipStore.swapSite(siteRef, [...inner.values()], tx);
+        await siteRefreshStore.upsertSite(siteRef, scanStart, tx);
+      });
+    } catch (err) {
+      logger.warn(`Site index scan failed for site ${siteRef}: ${err}`);
+      writeFailed = true;
+    }
+  }
+  let pruned = 0;
+  if (completed && !writeFailed) {
+    pruned = await siteRefreshStore.pruneMissing(scanStart);
+  }
+  logger.info(
+    `Site index scan: ${linksBySite.size} site(s) discovered${completed && !writeFailed ? `, ${pruned} stale pruned` : ", prune skipped (incomplete scan)"}`
+  );
+}
+
+exports.runScan = runScan;
+//# sourceMappingURL=runScan.cjs.js.map

package/dist/siteIndex/runScan.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runScan.cjs.js","sources":["../../src/siteIndex/runScan.ts"],"sourcesContent":["import {\n  stringifyEntityRef,\n  getCompoundEntityRef,\n  parseEntityRef,\n  RELATION_OWNED_BY,\n  type Entity,\n} from \"@backstage/catalog-model\";\nimport type { AuthService, LoggerService } from \"@backstage/backend-plugin-api\";\nimport type { CatalogService } from \"@backstage/plugin-catalog-node\";\nimport {\n  iterateAnnotatedEntities,\n  parseAnnotation,\n  toEntityPath,\n  RW_ANNOTATION,\n  type RwSiteConfig,\n} from \"@rwdocs/backstage-plugin-rw-common\";\nimport type { SectionOwnershipStore } from \"./SectionOwnershipStore\";\nimport type { SiteRefreshStore } from \"./SiteRefreshStore\";\nimport type { SectionOwnershipRow } from \"./types\";\n\nfunction ownerOf(entity: Entity): string | null {\n  const rel = (entity.relations ?? []).find((r) => r.type === RELATION_OWNED_BY);\n  return rel?.targetRef ?? null;\n}\n\nexport async function runScan(deps: {\n  catalog: Pick<CatalogService, \"queryEntities\">;\n  auth: AuthService;\n  logger: LoggerService;\n  siteConfig: RwSiteConfig;\n  sectionOwnershipStore: SectionOwnershipStore;\n  siteRefreshStore: SiteRefreshStore;\n  now?: () => Date;\n}): Promise<void> {\n  const { catalog, auth, logger, siteConfig, sectionOwnershipStore, siteRefreshStore } = deps;\n  const now = deps.now ?? (() => new Date());\n  const credentials = await auth.getOwnServiceCredentials();\n\n  // projectDir mode serves exactly one site; constrain discovery to it.\n  const onlySiteRef =\n    siteConfig.projectDir && siteConfig.entity\n      ? stringifyEntityRef(parseEntityRef(siteConfig.entity))\n      : undefined;\n\n  const scanStart = now();\n  // Dedup per-site links by section_ref (last-claim-wins) to avoid a PK violation on swap.\n  const linksBySite = new Map<string, Map<string, SectionOwnershipRow>>();\n  let completed = false;\n  let writeFailed = false;\n\n  try {\n    for await (const { entity } of iterateAnnotatedEntities(catalog, credentials)) {\n      const selfRef = stringifyEntityRef(getCompoundEntityRef(entity));\n      const parsed = parseAnnotation(\n        entity.metadata?.annotations?.[RW_ANNOTATION],\n        toEntityPath(selfRef),\n      );\n      if (!parsed) continue;\n      const siteRef = parsed.entityRef;\n      if (onlySiteRef && siteRef !== onlySiteRef) continue;\n\n      let link: SectionOwnershipRow | undefined;\n      if (parsed.sectionRef) {\n        link = {\n          site_ref: siteRef,\n          section_ref: parsed.sectionRef,\n          entity_ref: selfRef,\n          entity_owner_ref: ownerOf(entity),\n        };\n      } else if (parsed.entityRef === selfRef) {\n        // Self-host root claim: no explicit section ref, so use the site ref itself as the\n        // section_ref sentinel. At read time, ownership resolution falls back to this sentinel\n        // when no more-specific section link is found.\n        link = {\n          site_ref: siteRef,\n          section_ref: siteRef,\n          entity_ref: selfRef,\n          entity_owner_ref: ownerOf(entity),\n        };\n      }\n      // section-less claim on another site: ignored (matches legacy behavior)\n      if (!link) continue;\n\n      const inner = linksBySite.get(siteRef) ?? new Map<string, SectionOwnershipRow>();\n      inner.set(link.section_ref, link); // last-claim-wins dedup by section_ref\n      linksBySite.set(siteRef, inner);\n    }\n    completed = true;\n  } catch (err) {\n    logger.warn(`Site index scan iteration failed; skipping prune: ${err}`);\n  }\n\n  // Per site: swap links + upsert queue row atomically in one transaction.\n  for (const [siteRef, inner] of linksBySite) {\n    try {\n      await siteRefreshStore.transaction(async (tx) => {\n        await sectionOwnershipStore.swapSite(siteRef, [...inner.values()], tx);\n        await siteRefreshStore.upsertSite(siteRef, scanStart, tx);\n      });\n    } catch (err) {\n      logger.warn(`Site index scan failed for site ${siteRef}: ${err}`);\n      // A per-site write failure leaves last_discovery_at un-updated, so\n      // pruneMissing would incorrectly delete that still-present site. Mark the scan\n      // as dirty so we skip the prune entirely.\n      writeFailed = true;\n    }\n  }\n\n  // Prune only after a clean, complete iteration and all per-site writes succeeded —\n  // a partial/failed scan must not delete still-present sites from the queue.\n  let pruned = 0;\n  if (completed && !writeFailed) {\n    pruned = await siteRefreshStore.pruneMissing(scanStart);\n  }\n\n  logger.info(\n    `Site index scan: ${linksBySite.size} site(s) discovered${\n      completed && !writeFailed ? `, ${pruned} stale pruned` : \", prune skipped (incomplete scan)\"\n    }`,\n  );\n}\n"],"names":["RELATION_OWNED_BY","stringifyEntityRef","parseEntityRef","iterateAnnotatedEntities","getCompoundEntityRef","parseAnnotation","RW_ANNOTATION","toEntityPath"],"mappings":"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"}

package/dist/siteIndex/runWorker.cjs.js

@@ -0,0 +1,81 @@
+'use strict';
+
+var pLimit = require('p-limit');
+var backstagePluginRwCommon = require('@rwdocs/backstage-plugin-rw-common');
+var registryHash = require('./registryHash.cjs.js');
+var effectiveOwnership = require('./effectiveOwnership.cjs.js');
+var schedule = require('./schedule.cjs.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var pLimit__default = /*#__PURE__*/_interopDefaultCompat(pLimit);
+
+function sortSections(rows) {
+  return [...rows].sort((a, b) => a.section_ref.localeCompare(b.section_ref));
+}
+function sortPages(rows) {
+  return [...rows].sort(
+    (a, b) => a.section_ref.localeCompare(b.section_ref) || a.subpath.localeCompare(b.subpath)
+  );
+}
+async function runWorker(deps) {
+  const { logger, siteRefreshStore, registryStore, sectionOwnershipStore, makeSite } = deps;
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const claimNow = now();
+  const claimed = await siteRefreshStore.claimDue(
+    claimNow,
+    schedule.BATCH_SIZE,
+    new Date(claimNow.getTime() + schedule.LEASE_MS)
+  );
+  if (!claimed.length) return;
+  logger.info(`Site index worker: rebuilding ${claimed.length} site(s)`);
+  const limit = pLimit__default.default(schedule.CONCURRENCY);
+  await Promise.all(
+    claimed.map(
+      ({ siteRef, resultHash }) => limit(async () => {
+        try {
+          const site = makeSite(backstagePluginRwCommon.toEntityPath(siteRef));
+          const [rawSections, rawPages, claims] = await Promise.all([
+            site.listSections(),
+            site.listPages(),
+            sectionOwnershipStore.listForSite(siteRef)
+          ]);
+          const sections = sortSections(effectiveOwnership.computeSectionRows(siteRef, rawSections, claims));
+          const pages = sortPages(
+            rawPages.map((p) => ({
+              site_ref: siteRef,
+              section_ref: p.sectionRef,
+              subpath: p.subpath,
+              title: p.title
+            }))
+          );
+          const hash = registryHash.registryHash(sections, pages);
+          const changed = hash !== resultHash;
+          if (changed) {
+            await registryStore.swapSite(siteRef, sections, pages);
+          }
+          const completedAt = now();
+          await siteRefreshStore.completeSuccess(
+            siteRef,
+            hash,
+            schedule.jitteredNextUpdate(completedAt, schedule.INTERVAL_MS, deps.rng),
+            completedAt
+          );
+          logger.debug(
+            `Rebuilt ${siteRef}: ${sections.length} sections, ${pages.length} pages${changed ? "" : " (unchanged)"}`
+          );
+        } catch (err) {
+          logger.warn(`Site index rebuild failed for site ${siteRef}: ${err}`);
+          try {
+            await siteRefreshStore.recordError(siteRef, String(err));
+          } catch (recordErr) {
+            logger.warn(`Failed to record rebuild error for site ${siteRef}: ${recordErr}`);
+          }
+        }
+      })
+    )
+  );
+}
+
+exports.runWorker = runWorker;
+//# sourceMappingURL=runWorker.cjs.js.map

package/dist/siteIndex/runWorker.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runWorker.cjs.js","sources":["../../src/siteIndex/runWorker.ts"],"sourcesContent":["import pLimit from \"p-limit\";\nimport type { LoggerService } from \"@backstage/backend-plugin-api\";\nimport { toEntityPath } from \"@rwdocs/backstage-plugin-rw-common\";\nimport type { RwSite } from \"@rwdocs/core\";\nimport type { SiteRefreshStore } from \"./SiteRefreshStore\";\nimport type { RegistryStore } from \"./RegistryStore\";\nimport type { SectionOwnershipStore } from \"./SectionOwnershipStore\";\nimport type { SectionRow, PageRow } from \"./types\";\nimport { registryHash } from \"./registryHash\";\nimport { computeSectionRows } from \"./effectiveOwnership\";\nimport { jitteredNextUpdate, BATCH_SIZE, CONCURRENCY, LEASE_MS, INTERVAL_MS } from \"./schedule\";\n\nfunction sortSections(rows: SectionRow[]): SectionRow[] {\n  return [...rows].sort((a, b) => a.section_ref.localeCompare(b.section_ref));\n}\nfunction sortPages(rows: PageRow[]): PageRow[] {\n  return [...rows].sort(\n    (a, b) => a.section_ref.localeCompare(b.section_ref) || a.subpath.localeCompare(b.subpath),\n  );\n}\n\nexport async function runWorker(deps: {\n  logger: LoggerService;\n  siteRefreshStore: SiteRefreshStore;\n  registryStore: RegistryStore;\n  sectionOwnershipStore: Pick<SectionOwnershipStore, \"listForSite\">;\n  makeSite: (entityPath: string) => Pick<RwSite, \"listSections\" | \"listPages\">;\n  now?: () => Date;\n  rng?: () => number;\n}): Promise<void> {\n  const { logger, siteRefreshStore, registryStore, sectionOwnershipStore, makeSite } = deps;\n  const now = deps.now ?? (() => new Date());\n\n  const claimNow = now();\n  const claimed = await siteRefreshStore.claimDue(\n    claimNow,\n    BATCH_SIZE,\n    new Date(claimNow.getTime() + LEASE_MS),\n  );\n  if (!claimed.length) return;\n  logger.info(`Site index worker: rebuilding ${claimed.length} site(s)`);\n\n  const limit = pLimit(CONCURRENCY);\n  await Promise.all(\n    claimed.map(({ siteRef, resultHash }) =>\n      limit(async () => {\n        try {\n          const site = makeSite(toEntityPath(siteRef));\n          // listForSite is independent of the doc-structure reads, so fetch all three together.\n          const [rawSections, rawPages, claims] = await Promise.all([\n            site.listSections(),\n            site.listPages(),\n            sectionOwnershipStore.listForSite(siteRef),\n          ]);\n          // computeSectionRows folds the effective-ownership rollup into each dense section row.\n          // registryHash is order-sensitive (JSON.stringify) and listSections order is unspecified,\n          // so sort by section_ref for a stable hash.\n          const sections = sortSections(computeSectionRows(siteRef, rawSections, claims));\n          const pages = sortPages(\n            rawPages.map((p) => ({\n              site_ref: siteRef,\n              section_ref: p.sectionRef,\n              subpath: p.subpath,\n              title: p.title,\n            })),\n          );\n          const hash = registryHash(sections, pages);\n          const changed = hash !== resultHash;\n          if (changed) {\n            await registryStore.swapSite(siteRef, sections, pages);\n          }\n          const completedAt = now();\n          await siteRefreshStore.completeSuccess(\n            siteRef,\n            hash,\n            jitteredNextUpdate(completedAt, INTERVAL_MS, deps.rng),\n            completedAt,\n          );\n          logger.debug(\n            `Rebuilt ${siteRef}: ${sections.length} sections, ${pages.length} pages${\n              changed ? \"\" : \" (unchanged)\"\n            }`,\n          );\n        } catch (err) {\n          logger.warn(`Site index rebuild failed for site ${siteRef}: ${err}`);\n          // recordError is best-effort: if it also throws (e.g. DB down), swallow it so one\n          // site's failure never rejects Promise.all and aborts the rest of the batch.\n          try {\n            await siteRefreshStore.recordError(siteRef, String(err));\n          } catch (recordErr) {\n            logger.warn(`Failed to record rebuild error for site ${siteRef}: ${recordErr}`);\n          }\n        }\n      }),\n    ),\n  );\n}\n"],"names":["BATCH_SIZE","LEASE_MS","pLimit","CONCURRENCY","toEntityPath","computeSectionRows","registryHash","jitteredNextUpdate","INTERVAL_MS"],"mappings":"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"}

package/dist/siteIndex/schedule.cjs.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var core = require('@rwdocs/core');
+
+const INTERVAL_MS = 15 * 6e4;
+const LEASE_MS = 5 * 6e4;
+const BATCH_SIZE = 10;
+const CONCURRENCY = 4;
+function jitteredNextUpdate(now, intervalMs = INTERVAL_MS, rng = Math.random) {
+  return new Date(now.getTime() + intervalMs * (0.5 + rng()));
+}
+function makeSiteFactory(siteConfig) {
+  return (entityPath) => siteConfig.projectDir ? core.createSite({ projectDir: siteConfig.projectDir, diagrams: siteConfig.diagrams }) : core.createSite({
+    s3: { ...siteConfig.s3, entity: entityPath },
+    diagrams: siteConfig.diagrams
+  });
+}
+
+exports.BATCH_SIZE = BATCH_SIZE;
+exports.CONCURRENCY = CONCURRENCY;
+exports.INTERVAL_MS = INTERVAL_MS;
+exports.LEASE_MS = LEASE_MS;
+exports.jitteredNextUpdate = jitteredNextUpdate;
+exports.makeSiteFactory = makeSiteFactory;
+//# sourceMappingURL=schedule.cjs.js.map

package/dist/siteIndex/schedule.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.cjs.js","sources":["../../src/siteIndex/schedule.ts"],"sourcesContent":["import { createSite, type RwSite } from \"@rwdocs/core\";\nimport type { RwSiteConfig } from \"@rwdocs/backstage-plugin-rw-common\";\n\nexport const INTERVAL_MS = 15 * 60_000;\nexport const LEASE_MS = 5 * 60_000;\nexport const BATCH_SIZE = 10;\nexport const CONCURRENCY = 4;\n\n/** now + intervalMs * (0.5 + rng()); rng defaults to Math.random (range [0.5x, 1.5x]). */\nexport function jitteredNextUpdate(\n  now: Date,\n  intervalMs: number = INTERVAL_MS,\n  rng: () => number = Math.random,\n): Date {\n  return new Date(now.getTime() + intervalMs * (0.5 + rng()));\n}\n\n/** Build an `RwSite` for an entity path, branching projectDir vs S3 (matches the collator). */\nexport function makeSiteFactory(siteConfig: RwSiteConfig): (entityPath: string) => RwSite {\n  return (entityPath: string) =>\n    siteConfig.projectDir\n      ? createSite({ projectDir: siteConfig.projectDir, diagrams: siteConfig.diagrams })\n      : createSite({\n          s3: { ...siteConfig.s3!, entity: entityPath },\n          diagrams: siteConfig.diagrams,\n        });\n}\n"],"names":["createSite"],"mappings":";;;;AAGO,MAAM,cAAc,EAAA,GAAK;AACzB,MAAM,WAAW,CAAA,GAAI;AACrB,MAAM,UAAA,GAAa;AACnB,MAAM,WAAA,GAAc;AAGpB,SAAS,mBACd,GAAA,EACA,UAAA,GAAqB,WAAA,EACrB,GAAA,GAAoB,KAAK,MAAA,EACnB;AACN,EAAA,OAAO,IAAI,KAAK,GAAA,CAAI,OAAA,KAAY,UAAA,IAAc,GAAA,GAAM,KAAI,CAAE,CAAA;AAC5D;AAGO,SAAS,gBAAgB,UAAA,EAA0D;AACxF,EAAA,OAAO,CAAC,UAAA,KACN,UAAA,CAAW,UAAA,GACPA,gBAAW,EAAE,UAAA,EAAY,UAAA,CAAW,UAAA,EAAY,QAAA,EAAU,UAAA,CAAW,QAAA,EAAU,IAC/EA,eAAA,CAAW;AAAA,IACT,IAAI,EAAE,GAAG,UAAA,CAAW,EAAA,EAAK,QAAQ,UAAA,EAAW;AAAA,IAC5C,UAAU,UAAA,CAAW;AAAA,GACtB,CAAA;AACT;;;;;;;;;"}

package/migrations/20260621000000_init.js

@@ -0,0 +1,81 @@
+// @ts-check
+/** @param {import('knex').Knex} knex */
+exports.up = async function up(knex) {
+  await knex.schema.createTable('comments', table => {
+    table.uuid('id').primary(); // uuid v7
+    table.uuid('parent_id').nullable();
+    table.text('site_ref').notNullable();
+    table.text('page_ref').notNullable();
+    table.text('section_ref').notNullable();
+    table.text('author_ref').notNullable();
+    table.text('author_profile').nullable(); // JSON {displayName, picture?}
+    table.text('body').notNullable();
+    table.text('body_html').notNullable();
+    table.text('selectors').notNullable(); // JSON Selector[]
+    table.text('status').notNullable(); // 'open' | 'resolved'
+    table.dateTime('created_at').notNullable();
+    table.dateTime('updated_at').notNullable();
+    table.dateTime('resolved_at').nullable();
+    table.text('resolved_by').nullable();
+    table.dateTime('deleted_at').nullable();
+    table.index(['site_ref', 'page_ref'], 'comments_site_page_idx');
+    table.index(['site_ref', 'page_ref', 'status'], 'comments_site_page_status_idx');
+    table.index(['parent_id'], 'comments_parent_idx');
+    table.index(['section_ref'], 'comments_section_idx');
+    // The owner inbox lists open top-level threads paged by (updated_at, id) via
+    // keyset seek. status leads (equality-filtered to 'open') so the trailing
+    // (updated_at, id) supports a range scan for "load more", not a full sort of
+    // the owned set.
+    table.index(['status', 'updated_at', 'id'], 'comments_status_updated_idx');
+  });
+
+  await knex.schema.createTable('section_ownership', table => {
+    table.text('site_ref').notNullable();
+    table.text('section_ref').notNullable();
+    table.text('entity_ref').notNullable();
+    table.text('entity_owner_ref').nullable();
+    table.primary(['site_ref', 'section_ref']);
+    table.index(['entity_owner_ref'], 'section_ownership_owner_idx');
+  });
+
+  // The `sections` table is dense (one row per section) and carries both structure
+  // (parent_section_ref) and the effective-ownership rollup (entity_ref, entity_owner_ref, and an
+  // owner-relative section_path). The owner index serves the inbox's hot "sections owned by X" query.
+  await knex.schema.createTable('sections', table => {
+    table.text('site_ref').notNullable();
+    table.text('section_ref').notNullable();
+    table.text('section_path').notNullable();
+    table.text('parent_section_ref').nullable();
+    table.text('entity_ref').notNullable();
+    table.text('entity_owner_ref').nullable();
+    table.primary(['site_ref', 'section_ref']);
+    table.index(['entity_owner_ref'], 'sections_owner_idx');
+  });
+
+  await knex.schema.createTable('pages', table => {
+    table.text('site_ref').notNullable();
+    table.text('section_ref').notNullable();
+    table.text('subpath').notNullable();
+    table.text('title').notNullable();
+    table.primary(['site_ref', 'section_ref', 'subpath']);
+  });
+
+  await knex.schema.createTable('site_refresh', table => {
+    table.text('site_ref').primary();
+    table.dateTime('next_update_at').notNullable();
+    table.dateTime('last_built_at').nullable();
+    table.text('result_hash').nullable();
+    table.text('errors').nullable();
+    table.dateTime('last_discovery_at').notNullable();
+    table.index(['next_update_at'], 'site_refresh_next_update_idx');
+  });
+};
+
+/** @param {import('knex').Knex} knex */
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists('site_refresh');
+  await knex.schema.dropTableIfExists('pages');
+  await knex.schema.dropTableIfExists('sections');
+  await knex.schema.dropTableIfExists('section_ownership');
+  await knex.schema.dropTableIfExists('comments');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rwdocs/backstage-plugin-rw-backend",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,16 +28,16 @@
     "pluginId": "rw",
     "pluginPackages": [
       "@rwdocs/backstage-plugin-rw",
-      "@rwdocs/backstage-plugin-rw-backend"
+      "@rwdocs/backstage-plugin-rw-backend",
+      "@rwdocs/backstage-plugin-rw-common"
     ],
     "features": {
       ".": "@backstage/BackendFeature"
     }
   },
-  "configSchema": "config.d.ts",
   "files": [
     "dist",
-    "config.d.ts",
+    "migrations",
     "LICENSE-MIT",
     "LICENSE-APACHE"
   ],
@@ -56,25 +56,32 @@
     "@backstage/catalog-model": "^1.7.6",
     "@backstage/config": "^1.3.6",
     "@backstage/errors": "^1.2.7",
+    "@backstage/plugin-catalog-node": "^2.2.2",
+    "@backstage/plugin-events-node": "^0.4.23",
+    "@backstage/plugin-permission-common": "^0.9.9",
+    "@backstage/plugin-permission-node": "^0.11.1",
     "@backstage/types": "^1.2.2",
-    "@rwdocs/core": "^0.1.21",
+    "@rwdocs/backstage-plugin-rw-common": "^0.1.6",
+    "@rwdocs/core": "^0.1.28",
     "express": "^4.21.0",
-    "express-promise-router": "^4.1.0"
+    "express-promise-router": "^4.1.0",
+    "luxon": "^3.7.2",
+    "p-limit": "^3.1.0",
+    "uuid": "^14.0.0",
+    "zod": "^3.25.76 || ^4.0.0"
   },
   "peerDependencies": {
     "@backstage/backend-plugin-api": "^1.0.0"
   },
   "devDependencies": {
+    "@backstage/backend-defaults": "^0.17.3",
     "@backstage/backend-plugin-api": "^1.0.0",
     "@backstage/backend-test-utils": "^1.11.0",
     "@backstage/cli": "^0.36.0",
-    "@jest/environment-jsdom-abstract": "^30.2.0",
     "@types/express": "^4.17.0",
     "@types/jest": "^30.0.0",
-    "@types/jsdom": "^28",
     "@types/supertest": "^7.2.0",
     "jest": "^30.2.0",
-    "jsdom": "^29.0.0",
     "prettier": "^3.4.2",
     "supertest": "^7.2.2",
     "typescript": "^5.7.0"

package/config.d.ts

@@ -1,56 +0,0 @@
-export interface Config {
-  /** @visibility backend */
-  rw?: {
-    /**
-     * Local directory containing documentation source files.
-     * Mutually exclusive with `s3`.
-     */
-    projectDir?: string;
-    /**
-     * Entity ref that the local projectDir serves as (required when projectDir is set).
-     * Standard Backstage entity ref format: "kind:namespace/name" (e.g. "component:default/my-docs")
-     */
-    entity?: string;
-    /** Maximum number of cached RwSite instances. Default: 20. */
-    cacheSize?: number;
-    /**
-     * How often to check cached sites for upstream changes and reload if needed.
-     * If not set, no periodic reloading is performed.
-     *
-     * @example
-     * ```yaml
-     * rw:
-     *   reloadInterval: { minutes: 5 }
-     * ```
-     */
-    reloadInterval?: import("@backstage/types").HumanDuration;
-    /**
-     * S3 storage configuration. Shared across all entity sites.
-     * Mutually exclusive with `projectDir`.
-     */
-    s3?: {
-      /** S3 bucket name. */
-      bucket: string;
-      /** AWS region. */
-      region?: string;
-      /** Custom S3 endpoint URL. */
-      endpoint?: string;
-      /** Root path within the bucket. */
-      bucketRootPath?: string;
-      /** AWS access key ID. */
-      accessKeyId?: string;
-      /**
-       * AWS secret access key.
-       * @visibility secret
-       */
-      secretAccessKey?: string;
-    };
-    /** Diagram rendering configuration. Shared across all sites. */
-    diagrams?: {
-      /** Kroki server URL for rendering diagrams. */
-      krokiUrl?: string;
-      /** Diagram rendering DPI. */
-      dpi?: number;
-    };
-  };
-}

package/dist/entityPath.cjs.js

@@ -1,12 +0,0 @@
-'use strict';
-
-var catalogModel = require('@backstage/catalog-model');
-require('@backstage/errors');
-
-function toEntityPath(entityRef) {
-  const ref = catalogModel.parseEntityRef(entityRef);
-  return `${ref.namespace}/${ref.kind}/${ref.name}`.toLocaleLowerCase("en-US");
-}
-
-exports.toEntityPath = toEntityPath;
-//# sourceMappingURL=entityPath.cjs.js.map

package/dist/entityPath.cjs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"entityPath.cjs.js","sources":["../src/entityPath.ts"],"sourcesContent":["import { parseEntityRef } from \"@backstage/catalog-model\";\nimport { InputError } from \"@backstage/errors\";\n\n/**\n * Converts a Backstage entity ref (e.g. \"component:default/arch\") to the\n * slash-delimited, lowercased path format used in URLs and cache keys\n * (e.g. \"default/component/arch\").\n *\n * Uses namespace/kind/name ordering to match Backstage catalog URL convention.\n *\n * NOTE: The frontend plugin has a similar utility at\n * plugins/rw/src/components/entityPath.ts — keep in sync if changing logic.\n */\nexport function toEntityPath(entityRef: string): string {\n  const ref = parseEntityRef(entityRef);\n  return `${ref.namespace}/${ref.kind}/${ref.name}`.toLocaleLowerCase(\"en-US\");\n}\n\n/**\n * Converts a slash-delimited entity path (e.g. \"default/component/arch\")\n * back to the standard Backstage entity ref format (e.g. \"component:default/arch\").\n *\n * This is the inverse of `toEntityPath`. Note that the round-trip always\n * produces lowercased refs since `toEntityPath` lowercases its output.\n */\nexport function fromEntityPath(path: string): string {\n  const parts = path.split(\"/\");\n  if (parts.length !== 3 || parts.some((p) => !p)) {\n    throw new InputError(`Invalid entity path: \"${path}\" (expected \"namespace/kind/name\")`);\n  }\n  const [namespace, kind, name] = parts;\n  return `${kind}:${namespace}/${name}`;\n}\n"],"names":["parseEntityRef"],"mappings":";;;;;AAaO,SAAS,aAAa,SAAA,EAA2B;AACtD,EAAA,MAAM,GAAA,GAAMA,4BAAe,SAAS,CAAA;AACpC,EAAA,OAAO,CAAA,EAAG,GAAA,CAAI,SAAS,CAAA,CAAA,EAAI,GAAA,CAAI,IAAI,CAAA,CAAA,EAAI,GAAA,CAAI,IAAI,CAAA,CAAA,CAAG,iBAAA,CAAkB,OAAO,CAAA;AAC7E;;;;"}