Merge pull request #10 from shobman/feature/confluence-duplicate-title-handling

fix(confluence): resilient duplicate-title handling with suffix retry (v1.0.4)

Author: shobman

VERSION

@@ -1 +1 @@
-1.0.3
+1.0.4

src/connectors/confluence/README.md

@@ -171,6 +171,14 @@ If your Confluence space has existing pages with common names, add a `titleTempl
 | `(CW) %title%` | (CW) Problem |
 | `CW.Core - %title%` | CW.Core - Problem |
 
+### Duplicate titles
+
+Confluence requires page titles to be **unique within a space**. If an AIDOS artifact's derived title collides with an existing page elsewhere in the target space (not under the AIDOS root), the connector renames the new page by appending a numeric suffix: `Title`, then `Title (1)`, then `Title (2)`.
+
+The connector caps this at **3 total attempts** and hard-fails when all attempts are exhausted. Each rename logs two `WARNING:` lines in the publish output — one naming the collision, one explaining how to resolve it. If you see these warnings, rename the source file (or the conflicting Confluence pages) so titles are unique — the cap exists specifically to force the issue to be resolved rather than silently accumulating duplicates.
+
+On re-publish the connector checks the same suffix ladder, so previously-renamed pages are updated in place rather than creating a new copy each run.
+
 ### Multiple publish targets
 
 To add more targets later, add another key under `publish`:
@@ -222,7 +230,7 @@ cd aidos/src/connectors/confluence
 npm install
 ```
 
-Only one dependency (`marked` for markdown parsing). No test suite — the connector has been production-tested by running against real Confluence spaces.
+Only one dependency (`marked` for markdown parsing). Run `npm test` from this directory to execute the unit test suite (Node's built-in `node --test` runner, no external deps).
 
 ### Local dry-run
 
@@ -258,12 +266,14 @@ Use this only when you need to debug publish behaviour outside CI — the canoni
 ```
 src/connectors/confluence/
 ├── publish.js              ← Single entry point — walks .aidos/, converts markdown, publishes
+├── title-conflict.js       ← Pure helpers for duplicate-title detection and suffix resolution
+├── title-conflict.test.js  ← Unit tests for title-conflict helpers (node --test)
 ├── manifest.schema.json    ← JSON Schema for .aidos/manifest.json
 ├── package.json            ← { "type": "module", dependencies: { "marked": "..." } }
 └── README.md               ← This file
 ```
 
-The script is ~700 lines, self-contained, ESM, uses Node 20+ built-in fetch. Follow the structure (constants → auth → API helpers → markdown transforms → publish logic → main).
+The connector is ESM, uses Node 20+ built-in fetch, and has two modules: `publish.js` (the orchestration script) and `title-conflict.js` (pure helpers for duplicate-title handling). Follow the structure (constants → auth → API helpers → markdown transforms → publish logic → main).
 
 ### Versioning
 

src/connectors/confluence/package.json

@@ -1,8 +1,11 @@
 {
   "name": "aidos-confluence-connector",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "private": true,
   "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
   "dependencies": {
     "marked": "^15.0.0"
   }

src/connectors/confluence/publish.js

@@ -4,6 +4,10 @@ import { createHash } from "node:crypto";
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { marked } from "marked";
+import {
+  createWithRetryOnDuplicate,
+  findOwnedPageByTitle,
+} from "./title-conflict.js";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -506,38 +510,66 @@ async function publishPage(ctx, parentId, childPages, title, body, labels) {
     return existing ?? `dry-run-${title}`;
   }
 
-  // Check children of parent first, then search descendants of root as fallback
+  // Check direct children first (fast path), then search descendants of root
+  // with suffix tolerance so re-publishes find previously-renamed pages.
   let pageId = childPages.get(title);
+  let actualTitle = title;
   if (!pageId) {
-    const found = await findPageByTitle(baseUrl, ctx.rootPageId, title);
-    if (found) pageId = found.id;
+    const found = await findOwnedPageByTitle(title, (candidate) =>
+      findPageByTitle(baseUrl, ctx.rootPageId, candidate),
+    );
+    if (found) {
+      pageId = found.id;
+      actualTitle = found.title;
+    }
   }
 
   if (pageId) {
     // Check if content has changed via stored hash
     const storedHash = await getStoredHash(baseUrl, pageId);
     if (storedHash === hash) {
-      console.log("  Unchanged: %s (page %s)", title, pageId);
+      console.log("  Unchanged: %s (page %s)", actualTitle, pageId);
       ctx.stats.unchanged++;
       return pageId;
     }
 
     const page = await getPage(baseUrl, pageId);
-    await updatePage(baseUrl, pageId, title, body, page.version);
+    await updatePage(baseUrl, pageId, actualTitle, body, page.version);
     await addLabels(baseUrl, pageId, labels);
     await setStoredHash(baseUrl, pageId, hash);
-    console.log("  Updated: %s (page %s, v%d → v%d)", title, pageId, page.version, page.version + 1);
+    console.log(
+      "  Updated: %s (page %s, v%d → v%d)",
+      actualTitle,
+      pageId,
+      page.version,
+      page.version + 1,
+    );
     ctx.stats.updated++;
     return pageId;
   }
 
   // Two-step create: minimal body first (avoids Fabric editor macro
   // restrictions), then immediately update with full storage format.
-  const created = await createPage(baseUrl, spaceKey, parentId, title, "<p></p>");
-  await updatePage(baseUrl, created.id, title, body, 1);
+  // Confluence requires per-space title uniqueness — retry with numeric
+  // suffixes on duplicate-title 400s (capped in createWithRetryOnDuplicate).
+  const { result: created, title: createdTitle, renamed } =
+    await createWithRetryOnDuplicate(title, (candidate) =>
+      createPage(baseUrl, spaceKey, parentId, candidate, "<p></p>"),
+    );
+  if (renamed) {
+    console.log(
+      'WARNING: A page titled "%s" already exists elsewhere in this Confluence space. Created as "%s" instead.',
+      title,
+      createdTitle,
+    );
+    console.log(
+      "WARNING: Rename the source file to give it a unique Confluence page title — Confluence requires page titles to be unique within a space.",
+    );
+  }
+  await updatePage(baseUrl, created.id, createdTitle, body, 1);
   await addLabels(baseUrl, created.id, labels);
   await setStoredHash(baseUrl, created.id, hash);
-  console.log("  Created: %s (page %s)", title, created.id);
+  console.log("  Created: %s (page %s)", createdTitle, created.id);
   ctx.stats.created++;
   return created.id;
 }

src/connectors/confluence/title-conflict.js

@@ -0,0 +1,80 @@
+// Helpers for handling Confluence per-space title uniqueness.
+//
+// Confluence requires page titles to be unique within a space. When an AIDOS
+// artifact's derived title collides with an existing page elsewhere in the
+// space, we rename the new page with a numeric suffix — e.g. "Issues Log (1)".
+// The cap below hard-fails after this many attempts to force duplicates to be
+// resolved at the source rather than accumulating silently.
+
+export const MAX_TITLE_ATTEMPTS = 3;
+
+/**
+ * Build the title to try on attempt N of a create loop.
+ * Attempt 0 is the plain title; attempts 1+ append " (N)".
+ */
+export function suffixedTitle(baseTitle, attempt) {
+  return attempt === 0 ? baseTitle : `${baseTitle} (${attempt})`;
+}
+
+/**
+ * Detect the Confluence "duplicate title in space" 400 error by matching the
+ * two known server phrasings. Safe on non-Error inputs.
+ */
+export function isDuplicateTitleError(err) {
+  if (!err || typeof err !== "object" || typeof err.message !== "string") {
+    return false;
+  }
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes("a page with this title already exists") ||
+    msg.includes("a page already exists with the same title")
+  );
+}
+
+/**
+ * Attempt to create a page, retrying with numeric suffixes when Confluence
+ * rejects the title as a duplicate within the space. Caps at MAX_TITLE_ATTEMPTS
+ * total attempts — the last failure becomes a hard error that tells the user
+ * to rename the source file, so duplicates are resolved at the source rather
+ * than accumulating.
+ *
+ * @param {string} baseTitle  The desired title.
+ * @param {(title: string) => Promise<object>} doCreate  Caller's create impl.
+ * @returns {Promise<{ result: object, title: string, renamed: boolean }>}
+ */
+export async function createWithRetryOnDuplicate(baseTitle, doCreate) {
+  for (let attempt = 0; attempt < MAX_TITLE_ATTEMPTS; attempt++) {
+    const title = suffixedTitle(baseTitle, attempt);
+    try {
+      const result = await doCreate(title);
+      return { result, title, renamed: attempt > 0 };
+    } catch (err) {
+      if (!isDuplicateTitleError(err)) throw err;
+      if (attempt === MAX_TITLE_ATTEMPTS - 1) {
+        throw new Error(
+          `Cannot publish "${baseTitle}" to Confluence: the titles "${baseTitle}", "${baseTitle} (1)", and "${baseTitle} (2)" are all taken in the target space. ` +
+            `Confluence requires page titles to be unique within a space. ` +
+            `Rename the source file (or the conflicting Confluence pages) and re-run the publish.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Try to find a page the connector previously created, tolerant of numeric
+ * suffix renames. Walks the same ladder as createWithRetryOnDuplicate — plain,
+ * (1), (2), up to MAX_TITLE_ATTEMPTS — and returns the first hit.
+ *
+ * @param {string} baseTitle
+ * @param {(title: string) => Promise<{id: string, title: string} | null>} doFind
+ * @returns {Promise<{id: string, title: string} | null>}
+ */
+export async function findOwnedPageByTitle(baseTitle, doFind) {
+  for (let attempt = 0; attempt < MAX_TITLE_ATTEMPTS; attempt++) {
+    const title = suffixedTitle(baseTitle, attempt);
+    const page = await doFind(title);
+    if (page) return page;
+  }
+  return null;
+}