@repo-toolkit/confluence 0.19.0 → 0.21.0

package/cli.js

@@ -28,6 +28,7 @@ var DEFAULT_USER_AGENT = "repo-toolkit-confluence/1.0 (+node)";
 var MAX_LIMIT = 250;
 var MAX_ERROR_BODY_LENGTH = 8192;
 var MAX_PAGES_PER_QUERY = 100;
+var CONFLUENCE_MANAGED_LABEL = "repo-toolkit-confluence";
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
@@ -155,6 +156,44 @@ var ConfluenceClient = class {
       body: JSON.stringify(body)
     });
   }
+  async getPageDescendants(pageId) {
+    const query = new URLSearchParams({ limit: String(MAX_LIMIT) });
+    return this.listAll(this.v2Url(`/pages/${encodeURIComponent(pageId)}/descendants?${query.toString()}`));
+  }
+  async getPageLabels(pageId) {
+    const query = new URLSearchParams({ limit: String(MAX_LIMIT) });
+    return this.listAll(this.v2Url(`/pages/${encodeURIComponent(pageId)}/labels?${query.toString()}`));
+  }
+  async addManagedLabel(pageId) {
+    await this.requestJson(this.v1Url(`/content/${encodeURIComponent(pageId)}/label`), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify([{ prefix: "global", name: CONFLUENCE_MANAGED_LABEL }])
+    });
+  }
+  async deletePage(pageId) {
+    await this.requestJson(this.v2Url(`/pages/${encodeURIComponent(pageId)}`), { method: "DELETE" });
+  }
+  async listAll(startUrl) {
+    const results = [];
+    const visited = /* @__PURE__ */ new Set();
+    let pageCount = 0;
+    let nextUrl = startUrl;
+    while (nextUrl) {
+      pageCount += 1;
+      if (pageCount > MAX_PAGES_PER_QUERY) {
+        throw new ConfluenceApiError(`Pagination limit (${MAX_PAGES_PER_QUERY}) exceeded`, 0, nextUrl, "");
+      }
+      if (visited.has(nextUrl)) {
+        throw new ConfluenceApiError("Confluence pagination loop detected", 0, nextUrl, "");
+      }
+      visited.add(nextUrl);
+      const data = await this.requestJson(nextUrl, { method: "GET" });
+      results.push(...data.results);
+      nextUrl = resolveNextUrl(this.baseUrl, this.baseUrlOrigin, data._links?.next);
+    }
+    return results;
+  }
   async getAttachments(pageId) {
     const results = [];
     const visited = /* @__PURE__ */ new Set();
@@ -588,6 +627,64 @@ function titleFromSegment(segment) {
   }
   return segment;
 }
+var PAGE_TITLE_STRATEGIES = [
+  "filename-stem",
+  "filename",
+  "sentence-case-parent",
+  "sentence-case-parents",
+  "sentence-case-path"
+];
+var DEFAULT_PAGE_TITLE_STRATEGY = "filename-stem";
+function resolvePageTitleStrategy(value) {
+  if (value === void 0 || value === null) {
+    return DEFAULT_PAGE_TITLE_STRATEGY;
+  }
+  if (typeof value === "string" && PAGE_TITLE_STRATEGIES.includes(value)) {
+    return value;
+  }
+  throw new Error(
+    `Invalid pageTitleStrategy: expected one of ${PAGE_TITLE_STRATEGIES.join(", ")}, got ${JSON.stringify(value)}`
+  );
+}
+function sentenceCaseStem(filename) {
+  let stem = filename;
+  if (/\.md$/i.test(stem)) {
+    stem = stem.slice(0, stem.length - MARKDOWN_EXT.length);
+  }
+  let out = stem.replace(/[-_]+/g, " ").trim().replace(/[A-Z]/g, (c) => c.toLowerCase());
+  const firstLetter = /[a-z]/.exec(out);
+  if (firstLetter) {
+    const i = firstLetter.index;
+    out = out.slice(0, i) + out.charAt(i).toUpperCase() + out.slice(i + 1);
+  }
+  return out;
+}
+function pageTitleFromSegments(segments, strategy) {
+  const filename = segments.length > 0 ? segments[segments.length - 1] : "";
+  const parents = segments.slice(0, segments.length - 1);
+  switch (strategy) {
+    case "filename-stem":
+      return titleFromSegment(filename);
+    case "filename":
+      return filename;
+    case "sentence-case-parent": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents[parents.length - 1]})`;
+    }
+    case "sentence-case-parents": {
+      const title = sentenceCaseStem(filename);
+      if (parents.length === 0) {
+        return title;
+      }
+      return `${title} (${parents.join("/")})`;
+    }
+    case "sentence-case-path":
+      return `${sentenceCaseStem(filename)} (${[...parents, filename].join("/")})`;
+  }
+}
 
 // src/markdown.ts
 var STORAGE_LINE_BREAK = "<br />";
@@ -1603,6 +1700,141 @@ function runMmdc(cmdPath, source, outFile, timeoutMs, maxStreamBytes) {
   });
 }
 
+// src/parent-summary.ts
+var PARENT_SUMMARY_START_MARKER = "<!-- repo-toolkit-confluence:parent-summary:start -->";
+var PARENT_SUMMARY_END_MARKER = "<!-- repo-toolkit-confluence:parent-summary:end -->";
+function escapeCdata(text) {
+  return text.replace(/]]>/g, "]]]]><![CDATA[>");
+}
+function pageLink(pageId, title) {
+  const safeTitle = escapeCdata(title);
+  return `<ac:link><ri:page ri:content-id="${escapeXmlAttribute(pageId)}" /><ac:plain-text-link-body><![CDATA[${safeTitle}]]></ac:plain-text-link-body></ac:link>`;
+}
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let idx = 0;
+  while (true) {
+    const found = haystack.indexOf(needle, idx);
+    if (found === -1) {
+      break;
+    }
+    count += 1;
+    idx = found + needle.length;
+  }
+  return count;
+}
+function mergeParentSummaryBody(currentBody, generatedRegion) {
+  const startCount = countOccurrences(currentBody, PARENT_SUMMARY_START_MARKER);
+  const endCount = countOccurrences(currentBody, PARENT_SUMMARY_END_MARKER);
+  if (startCount === 0 && endCount === 0) {
+    if (currentBody === "") {
+      return generatedRegion;
+    }
+    const sep2 = currentBody.endsWith("\n") ? "" : "\n";
+    return currentBody + sep2 + generatedRegion;
+  }
+  if (startCount === 1 && endCount === 1) {
+    const startIdx = currentBody.indexOf(PARENT_SUMMARY_START_MARKER);
+    const endIdx = currentBody.indexOf(PARENT_SUMMARY_END_MARKER);
+    if (startIdx === -1 || endIdx === -1) {
+      throw new Error("malformed parent summary markers: missing marker");
+    }
+    if (startIdx > endIdx) {
+      throw new Error("malformed parent summary markers: start after end");
+    }
+    const before = currentBody.slice(0, startIdx);
+    const after = currentBody.slice(endIdx + PARENT_SUMMARY_END_MARKER.length);
+    if (countOccurrences(before, PARENT_SUMMARY_START_MARKER) !== 0 || countOccurrences(before, PARENT_SUMMARY_END_MARKER) !== 0) {
+      throw new Error("malformed parent summary markers: duplicate marker before region");
+    }
+    if (countOccurrences(after, PARENT_SUMMARY_START_MARKER) !== 0 || countOccurrences(after, PARENT_SUMMARY_END_MARKER) !== 0) {
+      throw new Error("malformed parent summary markers: duplicate marker after region");
+    }
+    return before + generatedRegion + after;
+  }
+  throw new Error("malformed or duplicate parent summary markers: expected 0 or 1 managed region");
+}
+function renderParentSummary(input) {
+  const lines = [];
+  lines.push(PARENT_SUMMARY_START_MARKER);
+  lines.push("<h2>Synced documentation</h2>");
+  if (input.repositoryUrl) {
+    const url = escapeXmlAttribute(input.repositoryUrl);
+    const text = escapeHtml(input.repositoryUrl);
+    lines.push(
+      `<p><em>This documentation subtree is synced from <a href="${url}">${text}</a> and maintained by <code>repo-toolkit-confluence</code>.</em></p>`
+    );
+  } else {
+    lines.push("<p><em>This documentation subtree is maintained by <code>repo-toolkit-confluence</code>.</em></p>");
+  }
+  lines.push("<h3>Statistics</h3>");
+  lines.push("<ul>");
+  lines.push(`<li>Markdown pages: ${input.stats.markdownPages}</li>`);
+  lines.push(`<li>Directory pages: ${input.stats.directoryPages}</li>`);
+  lines.push(`<li>Total managed pages: ${input.stats.totalPages}</li>`);
+  lines.push(`<li>Maximum depth: ${input.stats.maxDepth}</li>`);
+  lines.push(`<li>Attachment references: ${input.stats.attachmentReferences}</li>`);
+  lines.push(`<li>Mermaid blocks: ${input.stats.mermaidBlocks}</li>`);
+  lines.push("</ul>");
+  lines.push("<h3>Pages</h3>");
+  if (input.pages.length === 0) {
+    lines.push("<p>No managed child pages</p>");
+  } else {
+    lines.push(renderTree(input.pages));
+  }
+  lines.push("<h3>Ownership</h3>");
+  lines.push(
+    `<p>All generated pages carry the <code>${CONFLUENCE_MANAGED_LABEL}</code> label. On default sync, stale labeled pages not in the local tree are pruned; unlabeled pages are preserved. Use <code>clean: true</code> to move all safely deletable page descendants to trash before recreation.</p>`
+  );
+  lines.push(PARENT_SUMMARY_END_MARKER);
+  return lines.join("\n");
+}
+function renderTree(pages) {
+  const sorted = [...pages].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  const root = { children: /* @__PURE__ */ new Map(), key: "" };
+  for (const page of sorted) {
+    const parts = page.relativePath.split("/");
+    let node = root;
+    let currentPath = "";
+    for (let i = 0; i < parts.length; i += 1) {
+      const part = parts[i] ?? "";
+      currentPath = currentPath ? currentPath + "/" + part : part;
+      let child = node.children.get(part);
+      if (!child) {
+        child = { children: /* @__PURE__ */ new Map(), key: part };
+        node.children.set(part, child);
+      }
+      if (i === parts.length - 1) {
+        child.record = page;
+      }
+      node = child;
+    }
+  }
+  const renderNode = (node) => {
+    const entries = [...node.children.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    if (entries.length === 0) {
+      return "";
+    }
+    let html = "<ul>";
+    for (const [, child] of entries) {
+      const rec = child.record;
+      if (rec) {
+        const link = pageLink(rec.pageId, rec.title);
+        const kindLabel = rec.kind === "directory" ? "directory" : "page";
+        const pathCode = `<code>${escapeHtml(rec.relativePath)}</code>`;
+        const childrenHtml = renderNode(child);
+        html += `<li>${link} \u2014 ${pathCode} <em>(${kindLabel})</em>${childrenHtml}</li>`;
+      } else {
+        const childrenHtml = renderNode(child);
+        html += `<li>${escapeHtml(child.key)}${childrenHtml}</li>`;
+      }
+    }
+    html += "</ul>";
+    return html;
+  };
+  return renderNode(root);
+}
+
 // src/index.ts
 var LocalSyncValidationAggregateError = class extends Error {
   constructor(defects) {
@@ -1631,6 +1863,7 @@ function validateLocalSync(entries, plan) {
       }) : [];
       plans.push({
         entry,
+        title: pageTitleFromSegments(entry.segments, plan.pageTitleStrategy),
         html: body,
         mermaidBlocks,
         markdownDir,
@@ -1659,7 +1892,131 @@ var SyncMutationError = class extends Error {
     this.unprocessed = input.unprocessed;
   }
 };
+var ReconciliationError = class extends Error {
+  constructor(input) {
+    super(input.failure.error.message);
+    this.name = "ReconciliationError";
+    this.phase = input.phase;
+    this.completed = input.completed;
+    this.failure = input.failure;
+    this.unprocessed = input.unprocessed;
+  }
+};
+var ParentSummaryError = class extends Error {
+  constructor(input) {
+    super(input.failure.error.message);
+    this.name = "ParentSummaryError";
+    this.phase = "parent-summary";
+    this.changes = input.changes;
+    this.labelsAdded = input.labelsAdded;
+    this.cleanDeletions = input.cleanDeletions;
+    this.pruneDeletions = input.pruneDeletions;
+    this.blocked = input.blocked;
+    this.failure = input.failure;
+  }
+};
+function planStalePruning(input) {
+  const nodes = buildInventoryNodes(input.parentPageId, input.inventory);
+  const retained = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const isStale = (entry) => entry.type === "page" && entry.labeled && !input.expectedIds.has(entry.id) && entry.id !== input.parentPageId;
+  const visit = (node) => {
+    if (visited.has(node.entry.id)) {
+      return;
+    }
+    visited.add(node.entry.id);
+    let safe = isStale(node.entry);
+    for (const child of node.children) {
+      visit(child);
+      if (retained.has(child.entry.id)) {
+        safe = false;
+      }
+    }
+    if (!safe) {
+      retained.add(node.entry.id);
+    }
+  };
+  for (const node of nodes.values()) {
+    visit(node);
+  }
+  const deletions = deepestFirst([...nodes.values()].filter((n) => !retained.has(n.entry.id)));
+  const blocked = [...nodes.values()].filter((n) => retained.has(n.entry.id) && isStale(n.entry)).map((n) => n.entry.id).sort();
+  return { deletions, blocked };
+}
+function planCleanDeletions(input) {
+  const nodes = buildInventoryNodes(input.parentPageId, input.inventory);
+  for (const node of nodes.values()) {
+    if (node.entry.type !== "page") {
+      throw new Error(
+        `clean refused: descendant ${node.entry.id} has unsupported type "${node.entry.type}"; deleting its ancestors could remove content that cannot be restored by this tool`
+      );
+    }
+  }
+  return { deletions: deepestFirst([...nodes.values()]), blocked: [] };
+}
+function buildInventoryNodes(parentPageId, inventory) {
+  const nodes = /* @__PURE__ */ new Map();
+  for (const entry of inventory) {
+    if (entry.id === parentPageId) {
+      continue;
+    }
+    if (nodes.has(entry.id)) {
+      throw new Error(`Incomplete descendant inventory: duplicate id ${entry.id}`);
+    }
+    nodes.set(entry.id, { entry, depth: -1, children: [] });
+  }
+  const depthOf = (node) => {
+    if (node.depth >= 0) {
+      return node.depth;
+    }
+    if (typeof node.entry.depth === "number") {
+      node.depth = node.entry.depth;
+      return node.depth;
+    }
+    let depth = 0;
+    let current = node;
+    const seen = /* @__PURE__ */ new Set([node.entry.id]);
+    while (true) {
+      const pid = current.entry.parentId;
+      if (pid === parentPageId) {
+        depth += 1;
+        node.depth = depth;
+        return depth;
+      }
+      if (!pid) {
+        throw new Error(`Incomplete descendant inventory: missing parent for ${node.entry.id}`);
+      }
+      if (seen.has(pid)) {
+        throw new Error(`Incomplete descendant inventory: parent cycle at ${pid}`);
+      }
+      seen.add(pid);
+      const parent = nodes.get(pid);
+      if (!parent) {
+        throw new Error(
+          `Incomplete descendant inventory: ancestor ${pid} of ${node.entry.id} is missing from the listing`
+        );
+      }
+      depth += 1;
+      current = parent;
+    }
+  };
+  for (const node of nodes.values()) {
+    depthOf(node);
+    const pid = node.entry.parentId;
+    if (pid !== void 0 && pid !== parentPageId) {
+      nodes.get(pid)?.children.push(node);
+    }
+  }
+  return nodes;
+}
+function deepestFirst(nodes) {
+  return [...nodes].sort((a, b) => b.depth - a.depth !== 0 ? b.depth - a.depth : a.entry.id.localeCompare(b.entry.id)).map((n) => n.entry.id);
+}
+function hasManagedMarker(labels) {
+  return labels.some((label) => label.name === CONFLUENCE_MANAGED_LABEL && label.prefix === "global");
+}
 function resolveConfluenceSyncPlan(options = {}) {
+  const pageTitleStrategy = resolvePageTitleStrategy(options.pageTitleStrategy);
   const cwd = resolve2(options.cwd ?? process.cwd());
   const folder = resolveInputPath(cwd, options.folder ?? "");
   if (!options.folder) {
@@ -1706,7 +2063,10 @@ function resolveConfluenceSyncPlan(options = {}) {
     skipUnchanged: options.skipUnchanged ?? true,
     dryRun: options.dryRun ?? false,
     renderHtmlBlocks: options.renderHtmlBlocks === true,
-    repositoryUrl
+    repositoryUrl,
+    clean: options.clean ?? false,
+    updateParentPage: options.updateParentPage ?? true,
+    pageTitleStrategy
   };
 }
 async function syncConfluenceToDocs(options = {}) {
@@ -1715,19 +2075,44 @@ async function syncConfluenceToDocs(options = {}) {
   const tree = await readDocTree(plan.folder);
   if (tree.entries.length === 0) {
     log(`No markdown files found under ${plan.folder}`);
-    return;
   }
-  validateLocalHierarchy(tree.entries);
   const localPlan = validateLocalSync(tree.entries, plan);
+  validateLocalHierarchy(localPlan.entries, plan.pageTitleStrategy);
   if (plan.dryRun) {
     log("[dry-run] Walking documentation tree only.");
     for (const entryPlan of localPlan.entries) {
       const attCount = entryPlan.attachments.length;
       const mermaidCount = entryPlan.mermaidBlocks.length;
       log(
-        `[dry-run] would sync ${entryPlan.entry.segments.join("/")}` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
+        `[dry-run] would sync ${entryPlan.entry.segments.join("/")} as "${entryPlan.title}"` + (attCount > 0 ? ` (${attCount} attachment${attCount === 1 ? "" : "s"} validated)` : "") + (mermaidCount > 0 ? ` (${mermaidCount} mermaid block${mermaidCount === 1 ? "" : "s"})` : "")
       );
     }
+    if (plan.clean) {
+      log(
+        "[dry-run] clean requested: a real sync would move every page descendant of the target page to trash before recreating the local hierarchy."
+      );
+    }
+    log(
+      "[dry-run] a real sync would label every mapped page with the ownership marker and prune stale labeled descendants."
+    );
+    if (plan.updateParentPage) {
+      const stats = computeDryRunStats(localPlan);
+      log(
+        `[dry-run] parent summary: Markdown pages: ${stats.markdownPages}, Directory pages: ${stats.directoryPages}, Total managed pages: ${stats.totalPages}, Maximum depth: ${stats.maxDepth}, Attachment references: ${stats.attachmentReferences}, Mermaid blocks: ${stats.mermaidBlocks}`
+      );
+      if (localPlan.entries.length === 0) {
+        log("[dry-run] parent tree: No managed child pages");
+      } else {
+        for (const entryPlan of localPlan.entries) {
+          const dirParts = entryPlan.entry.segments.slice(0, -1);
+          for (let i = 0; i < dirParts.length; i += 1) {
+            const dirPath = dirParts.slice(0, i + 1).join("/");
+            log(`[dry-run] parent tree: ${dirPath} (directory) => "${dirParts[i] ?? ""}"`);
+          }
+          log(`[dry-run] parent tree: ${entryPlan.entry.segments.join("/")} (page) => "${entryPlan.title}"`);
+        }
+      }
+    }
     return;
   }
   const client = options.client ?? new ConfluenceClient({
@@ -1735,13 +2120,29 @@ async function syncConfluenceToDocs(options = {}) {
     username: plan.username,
     apiToken: plan.apiToken
   });
+  const labelsAdded = [];
+  const cleanDeletions = [];
+  const pruneDeletions = [];
+  const blocked = [];
+  if (plan.clean) {
+    const descendants = await client.getPageDescendants(plan.parentPageId);
+    const inventory = descendants.filter((d) => d.id !== plan.parentPageId).map((d) => toInventoryEntry(d, false));
+    const cleanPlan = planCleanDeletions({ parentPageId: plan.parentPageId, inventory });
+    await executeDeletions(cleanPlan.deletions, "clean", client, log, cleanDeletions);
+  }
   const spaceId = await client.getSpaceIdByKey(plan.spaceKey);
   const cache = new PageTitleCache(spaceId, client);
+  const syncState = {
+    mappedIds: /* @__PURE__ */ new Set(),
+    ensuredLabels: /* @__PURE__ */ new Set(),
+    labelsAdded,
+    mappedRecords: /* @__PURE__ */ new Map()
+  };
   const changes = [];
   for (let i = 0; i < localPlan.entries.length; i += 1) {
     const entryPlan = localPlan.entries[i];
     try {
-      await syncEntry(entryPlan, plan, client, cache, log, changes);
+      await syncEntry(entryPlan, plan, client, cache, log, changes, syncState);
     } catch (error) {
       throw new SyncMutationError({
         changes,
@@ -1750,20 +2151,207 @@ async function syncConfluenceToDocs(options = {}) {
       });
     }
   }
-  return { changes };
+  if (!plan.clean) {
+    const descendants = await client.getPageDescendants(plan.parentPageId);
+    const inventory = [];
+    for (const d of descendants) {
+      if (d.id === plan.parentPageId) {
+        continue;
+      }
+      if (d.type !== "page") {
+        inventory.push(toInventoryEntry(d, false));
+        continue;
+      }
+      if (syncState.mappedIds.has(d.id)) {
+        inventory.push(toInventoryEntry(d, true));
+        continue;
+      }
+      const labels = await client.getPageLabels(d.id);
+      inventory.push(toInventoryEntry(d, hasManagedMarker(labels)));
+    }
+    const prunePlan = planStalePruning({
+      parentPageId: plan.parentPageId,
+      expectedIds: syncState.mappedIds,
+      inventory
+    });
+    await executeDeletions(prunePlan.deletions, "prune", client, log, pruneDeletions);
+    for (const pageId of prunePlan.blocked) {
+      blocked.push(pageId);
+      log(`blocked: stale page ${pageId} retained because it has unlabeled, non-page, or expected descendants`);
+    }
+  }
+  let parentStatus = "skipped";
+  if (plan.updateParentPage) {
+    try {
+      const parentPage = await client.getPage(plan.parentPageId);
+      const stats = computeParentStats(localPlan, syncState);
+      const pages = [...syncState.mappedRecords.values()].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+      const region = renderParentSummary({ repositoryUrl: plan.repositoryUrl, stats, pages });
+      const currentBody = parentPage.body?.storage?.value ?? "";
+      const merged = mergeParentSummaryBody(currentBody, region);
+      if (merged === currentBody) {
+        log(`parent-unchanged: page ${plan.parentPageId}`);
+        parentStatus = "unchanged";
+      } else {
+        await client.updatePage({
+          id: plan.parentPageId,
+          title: parentPage.title,
+          body: { representation: "storage", value: merged },
+          version: { number: (parentPage.version?.number ?? 0) + 1, message: plan.versionMessage }
+        });
+        log(`parent-updated: page ${plan.parentPageId}`);
+        parentStatus = "updated";
+      }
+    } catch (error) {
+      throw new ParentSummaryError({
+        changes,
+        labelsAdded: [...labelsAdded],
+        cleanDeletions: [...cleanDeletions],
+        pruneDeletions: [...pruneDeletions],
+        blocked: [...blocked],
+        failure: { pageId: plan.parentPageId, error: error instanceof Error ? error : new Error(String(error)) }
+      });
+    }
+  }
+  return { changes, labelsAdded, cleanDeletions, pruneDeletions, blocked, parentStatus };
+}
+function computeParentStats(localPlan, state) {
+  const dirSet = /* @__PURE__ */ new Set();
+  let maxDepth = 0;
+  let attachmentReferences = 0;
+  let mermaidBlocks = 0;
+  for (const entryPlan of localPlan.entries) {
+    const segs = entryPlan.entry.segments;
+    if (segs.length > maxDepth) {
+      maxDepth = segs.length;
+    }
+    for (let i = 0; i < segs.length - 1; i += 1) {
+      dirSet.add(segs.slice(0, i + 1).join("/"));
+    }
+    attachmentReferences += entryPlan.attachments.length;
+    mermaidBlocks += entryPlan.mermaidBlocks.length;
+  }
+  const markdownPages = localPlan.entries.length;
+  const directoryPages = dirSet.size;
+  const totalPages = state.mappedRecords.size;
+  const effectiveMaxDepth = localPlan.entries.length === 0 ? 0 : maxDepth;
+  return {
+    markdownPages,
+    directoryPages,
+    totalPages: totalPages > 0 ? totalPages : directoryPages + markdownPages,
+    maxDepth: effectiveMaxDepth,
+    attachmentReferences,
+    mermaidBlocks
+  };
 }
-async function syncEntry(entryPlan, plan, client, cache, log, changes) {
+function computeDryRunStats(localPlan) {
+  const dirSet = /* @__PURE__ */ new Set();
+  let maxDepth = 0;
+  let attachmentReferences = 0;
+  let mermaidBlocks = 0;
+  for (const entryPlan of localPlan.entries) {
+    const segs = entryPlan.entry.segments;
+    if (segs.length > maxDepth) {
+      maxDepth = segs.length;
+    }
+    for (let i = 0; i < segs.length - 1; i += 1) {
+      dirSet.add(segs.slice(0, i + 1).join("/"));
+    }
+    attachmentReferences += entryPlan.attachments.length;
+    mermaidBlocks += entryPlan.mermaidBlocks.length;
+  }
+  const markdownPages = localPlan.entries.length;
+  const directoryPages = dirSet.size;
+  return {
+    markdownPages,
+    directoryPages,
+    totalPages: directoryPages + markdownPages,
+    maxDepth: markdownPages === 0 ? 0 : maxDepth,
+    attachmentReferences,
+    mermaidBlocks
+  };
+}
+function toInventoryEntry(d, labeled) {
+  const entry = { id: d.id, type: d.type, labeled };
+  if (d.parentId !== void 0) {
+    entry.parentId = d.parentId;
+  }
+  if (d.depth !== void 0) {
+    entry.depth = d.depth;
+  }
+  if (d.title !== void 0) {
+    entry.title = d.title;
+  }
+  return entry;
+}
+async function ensureManagedLabel(pageId, client, state, log) {
+  if (state.ensuredLabels.has(pageId)) {
+    return;
+  }
+  const labels = await client.getPageLabels(pageId);
+  if (!hasManagedMarker(labels)) {
+    await client.addManagedLabel(pageId);
+    state.labelsAdded.push(pageId);
+    log(`labeled: page ${pageId}`);
+  }
+  state.ensuredLabels.add(pageId);
+}
+async function executeDeletions(ids, phase, client, log, evidence) {
+  for (let i = 0; i < ids.length; i += 1) {
+    const pageId = ids[i];
+    if (pageId === void 0) {
+      continue;
+    }
+    try {
+      await client.deletePage(pageId);
+      evidence.push(pageId);
+      log(`${phase === "clean" ? "clean" : "pruned"}: trashed page ${pageId}`);
+    } catch (error) {
+      throw new ReconciliationError({
+        phase,
+        completed: [...evidence],
+        failure: { pageId, error: error instanceof Error ? error : new Error(String(error)) },
+        unprocessed: ids.slice(i + 1)
+      });
+    }
+  }
+}
+async function syncEntry(entryPlan, plan, client, cache, log, changes, state) {
   const { entry, html: precomputedHtml, mermaidBlocks, markdownDir, hasLocalImages, hasMermaidBlocks } = entryPlan;
   const segments = entry.segments;
   if (segments.length === 0) {
     return;
   }
   let currentParentId = plan.parentPageId;
+  const recordDirectory = (relativePath, title, pageId, depth) => {
+    if (!state.mappedRecords.has(relativePath)) {
+      state.mappedRecords.set(relativePath, {
+        relativePath,
+        kind: "directory",
+        title,
+        pageId,
+        depth,
+        attachmentCount: 0,
+        mermaidCount: 0
+      });
+    }
+  };
+  const recordLeaf = (relativePath, title, pageId, depth) => {
+    state.mappedRecords.set(relativePath, {
+      relativePath,
+      kind: "leaf",
+      title,
+      pageId,
+      depth,
+      attachmentCount: entryPlan.attachments.length,
+      mermaidCount: entryPlan.mermaidBlocks.length
+    });
+  };
   for (let idx = 0; idx < segments.length; idx += 1) {
     const isLast = idx === segments.length - 1;
     const segment = segments[idx] ?? "";
     if (isLast && isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = entryPlan.title;
       const leafNeedsUploads = hasLocalImages || hasMermaidBlocks;
       const existing = await cache.find(title, currentParentId);
       if (!existing && !leafNeedsUploads) {
@@ -1772,12 +2360,18 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
           parentId: currentParentId,
           body: { representation: "storage", value: precomputedHtml }
         });
+        state.mappedIds.add(pageId2);
+        await ensureManagedLabel(pageId2, client, state, log);
+        recordLeaf(segments.join("/"), title, pageId2, segments.length);
         log(`created: ${segments.join("/")} (page ${pageId2})`);
         changes.push({ entry, pageId: pageId2, kind: "created" });
         return;
       }
       const existingPage = existing ?? await cache.findOrCreate(title, currentParentId);
       const pageId = existingPage.id;
+      state.mappedIds.add(pageId);
+      await ensureManagedLabel(pageId, client, state, log);
+      recordLeaf(segments.join("/"), title, pageId, segments.length);
       const current = await client.getPage(pageId);
       const currentBody = current.body?.storage?.value ?? "";
       let body = precomputedHtml;
@@ -1822,12 +2416,18 @@ async function syncEntry(entryPlan, plan, client, cache, log, changes) {
       return;
     }
     if (isMarkdownName(segment)) {
-      const title = titleFromSegment(segment);
+      const title = pageTitleFromSegments(segments.slice(0, idx + 1), plan.pageTitleStrategy);
       const page2 = await cache.findOrCreate(title, currentParentId);
+      state.mappedIds.add(page2.id);
+      await ensureManagedLabel(page2.id, client, state, log);
+      recordDirectory(segments.slice(0, idx + 1).join("/"), title, page2.id, idx + 1);
       currentParentId = page2.id;
       continue;
     }
     const page = await cache.findOrCreate(segment, currentParentId);
+    state.mappedIds.add(page.id);
+    await ensureManagedLabel(page.id, client, state, log);
+    recordDirectory(segments.slice(0, idx + 1).join("/"), segment, page.id, idx + 1);
     currentParentId = page.id;
   }
 }
@@ -1953,14 +2553,15 @@ async function predictBody(html, mermaidBlocks, pageId, client, ctx) {
   }
   return predicted;
 }
-function validateLocalHierarchy(entries) {
+function validateLocalHierarchy(entries, strategy) {
   const seen = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
+  for (const entryPlan of entries) {
+    const { entry } = entryPlan;
     let parentKey = "";
     for (let index = 0; index < entry.segments.length; index += 1) {
       const segment = entry.segments[index] ?? "";
       const isLast = index === entry.segments.length - 1;
-      const title = isMarkdownName(segment) ? titleFromSegment(segment) : segment;
+      const title = isMarkdownName(segment) ? isLast ? entryPlan.title : pageTitleFromSegments(entry.segments.slice(0, index + 1), strategy) : segment;
       const kind = isLast && isMarkdownName(segment) ? "file" : "dir";
       const key = `${parentKey}::${title}`;
       const existing = seen.get(key);
@@ -1986,14 +2587,17 @@ var SPECS = [
   { name: "parent-page-id" },
   { name: "version-message" },
   { name: "repository-url" },
+  { name: "page-title-strategy" },
   { name: "skip-unchanged", boolean: true, negatable: true },
   { name: "dry-run", boolean: true },
   { name: "render-html-blocks", boolean: true },
+  { name: "clean", boolean: true },
+  { name: "update-parent-page", boolean: true, negatable: true },
   INTERACTIVE_FLAG
 ];
 var ENV_TRUTHY = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
 var ENV_FALSY = /* @__PURE__ */ new Set(["false", "0", "no", "off", ""]);
-var BOOLEAN_ENV_KEYS = /* @__PURE__ */ new Set(["skipUnchanged", "dryRun", "renderHtmlBlocks"]);
+var BOOLEAN_ENV_KEYS = /* @__PURE__ */ new Set(["skipUnchanged", "dryRun", "renderHtmlBlocks", "clean", "updateParentPage"]);
 function isBooleanOption(key) {
   return BOOLEAN_ENV_KEYS.has(key);
 }
@@ -2031,9 +2635,12 @@ Environment variables (CLI form; GitHub Action INPUT_* form is also read):
   CONFLUENCE_PARENT_PAGE_ID            Numeric parent page id
   CONFLUENCE_VERSION_MESSAGE            Version-message suffix for every PUT
   CONFLUENCE_REPOSITORY_URL            Repository URL appended to synced pages
+  CONFLUENCE_PAGE_TITLE_STRATEGY       Leaf page title strategy (default: filename-stem)
   CONFLUENCE_SKIP_UNCHANGED            true|false (default: true)
   CONFLUENCE_DRY_RUN                   true|false (default: false)
   CONFLUENCE_RENDER_HTML_BLOCKS        true|false (default: false)
+  CONFLUENCE_CLEAN                     true|false (default: false)
+  CONFLUENCE_UPDATE_PARENT_PAGE        true|false (default: true)
   INPUT_<UPPER-FLAG>                   GitHub Actions input form (lower precedence)
 
 Note: prefer CONFLUENCE_API_TOKEN_FILE or CONFLUENCE_API_TOKEN over
@@ -2051,11 +2658,18 @@ Options:
   --parent-page-id <id>         Numeric page id under which docs will be published (required)
   --version-message <text>      Commit message appended to every page/attachment PUT
   --repository-url <url>        Repository URL appended to synced pages as an italic notice
+  --page-title-strategy <value> Leaf page title strategy: filename-stem (default), filename,
+                                sentence-case-parent, sentence-case-parents, sentence-case-path
   --skip-unchanged               Skip pages whose body is unchanged (default: true)
   --no-skip-unchanged           Re-upload every page even when unchanged
   --dry-run                     Walk the doc tree and print the plan without API calls
   --render-html-blocks          Render \`\`\`html fenced blocks as inline HTML via the
                                 Confluence html macro (default: false; emits as code box)
+  --clean                       Move all page descendants to trash before recreation (default: false).
+                                WARNING: destructive \u2014 all page descendants, including manual/unlabeled
+                                pages, are moved to trash; parentPageId is retained.
+  --update-parent-page          Update parent page summary region (default: true)
+  --no-update-parent-page       Do not update parent page summary
   -i, --interactive             Prompt interactively for missing non-secret required values
   -h, --help                    Show this help message
 `);
@@ -2092,9 +2706,12 @@ var ENV_BINDINGS = [
   { envName: "INPUT_PARENT-PAGE-ID", key: "parentPageId", kind: "string" },
   { envName: "INPUT_VERSION-MESSAGE", key: "versionMessage", kind: "string" },
   { envName: "INPUT_REPOSITORY-URL", key: "repositoryUrl", kind: "string" },
+  { envName: "INPUT_PAGE-TITLE-STRATEGY", key: "pageTitleStrategy", kind: "string" },
   { envName: "INPUT_DRY-RUN", key: "dryRun", kind: "boolean" },
   { envName: "INPUT_SKIP-UNCHANGED", key: "skipUnchanged", kind: "boolean" },
   { envName: "INPUT_RENDER-HTML-BLOCKS", key: "renderHtmlBlocks", kind: "boolean" },
+  { envName: "INPUT_CLEAN", key: "clean", kind: "boolean" },
+  { envName: "INPUT_UPDATE-PARENT-PAGE", key: "updateParentPage", kind: "boolean" },
   { envName: "CONFLUENCE_FOLDER", key: "folder", kind: "string" },
   { envName: "CONFLUENCE_USERNAME", key: "username", kind: "string" },
   { envName: "CONFLUENCE_API_TOKEN", key: "apiToken", kind: "string" },
@@ -2104,9 +2721,12 @@ var ENV_BINDINGS = [
   { envName: "CONFLUENCE_PARENT_PAGE_ID", key: "parentPageId", kind: "string" },
   { envName: "CONFLUENCE_VERSION_MESSAGE", key: "versionMessage", kind: "string" },
   { envName: "CONFLUENCE_REPOSITORY_URL", key: "repositoryUrl", kind: "string" },
+  { envName: "CONFLUENCE_PAGE_TITLE_STRATEGY", key: "pageTitleStrategy", kind: "string" },
   { envName: "CONFLUENCE_DRY_RUN", key: "dryRun", kind: "boolean" },
   { envName: "CONFLUENCE_SKIP_UNCHANGED", key: "skipUnchanged", kind: "boolean" },
-  { envName: "CONFLUENCE_RENDER_HTML_BLOCKS", key: "renderHtmlBlocks", kind: "boolean" }
+  { envName: "CONFLUENCE_RENDER_HTML_BLOCKS", key: "renderHtmlBlocks", kind: "boolean" },
+  { envName: "CONFLUENCE_CLEAN", key: "clean", kind: "boolean" },
+  { envName: "CONFLUENCE_UPDATE_PARENT_PAGE", key: "updateParentPage", kind: "boolean" }
 ];
 function optionsFromEnv(env = process.env) {
   const options = {};
@@ -2116,6 +2736,10 @@ function optionsFromEnv(env = process.env) {
       continue;
     }
     if (kind === "string") {
+      if (key === "pageTitleStrategy") {
+        options[key] = raw;
+        continue;
+      }
       if (!isStringOptionKey(key)) {
         continue;
       }
@@ -2156,6 +2780,9 @@ function buildOptions(result) {
   setIfString(options, "parentPageId", values["parent-page-id"]);
   setIfString(options, "versionMessage", values["version-message"]);
   setIfString(options, "repositoryUrl", values["repository-url"]);
+  if (values["page-title-strategy"] !== void 0) {
+    options.pageTitleStrategy = values["page-title-strategy"];
+  }
   if (values["skip-unchanged"] !== void 0) {
     options.skipUnchanged = values["skip-unchanged"] === "true";
   }
@@ -2165,6 +2792,12 @@ function buildOptions(result) {
   if (values["render-html-blocks"] !== void 0) {
     options.renderHtmlBlocks = true;
   }
+  if (values["clean"] !== void 0) {
+    options.clean = values["clean"] === "true";
+  }
+  if (values["update-parent-page"] !== void 0) {
+    options.updateParentPage = values["update-parent-page"] === "true";
+  }
   return options;
 }
 async function resolveConfluenceOptions(args) {