@crypto512/jicon-mcp 1.1.1 → 1.2.0

package/dist/confluence/tools.js

@@ -7,7 +7,9 @@ import { contentBuffer } from "../utils/content-buffer.js";
 import { formatPageMetadata } from "./formatters.js";
 import { validateXhtmlAsync, parseXhtml, parseStructure, serializeXhtml, enhanceXhtmlError } from "../utils/xhtml/index.js";
 import { detectRawPlantUml, detectDiagramType } from "../utils/xhtml/plantuml.js";
-import { expandPlantUmlInXhtml } from "../utils/plantuml/index.js";
+import { expandPlantUmlInXhtml, collapseExpandedIncludesInXhtml } from "../utils/plantuml/index.js";
+import { parseUrl } from "../utils/url-tools.js";
+import { DEFAULT_PAGE_EXPAND } from "./defaults.js";
 /**
  * Generate a summary of content structure for draft responses.
  * Helps AI assistants verify that diagrams and other elements are included.
@@ -225,7 +227,7 @@ WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
                                 hint += "- ✅ RIGHT: (text~\"a\" OR text~\"b\") - Each term needs its own text~\n";
                             }
                             hint += "\nExamples:\n";
-                            hint += "  text~\"Nicolas Pernoud\" - finds pages mentioning this person\n";
+                            hint += "  text~\"Mike Tasc\" - finds pages mentioning this person\n";
                             hint += "  text~\"meeting\" AND space=MESH - finds meetings in MESH space\n";
                             hint += "  title~\"sprint review\" - finds pages with sprint review in title";
                             return formatError({
@@ -256,7 +258,7 @@ WARNING: Use text~ (not content~ or body~). Use space KEY (not name).`,
 PREFERRED method when you have a page ID from search results. Faster and more reliable than get_page_by_title.
 
 Returns pageId, version, bufferId, and structure (element IDs) for structured editing.
-Use buffer_edit with element IDs to modify, then confluence_draft_create for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
             inputSchema: z.object({
                 pageId: z.coerce.string().describe("Page ID (accepts string or number)"),
                 expand: z
@@ -267,7 +269,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
             handler: async (args) => {
                 try {
                     const result = await client.getPage(args.pageId, args.expand);
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -284,7 +288,7 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                         bufferId,
                         ...(structure && { structure }),
                         contentSize: content.length,
-                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create for user review.",
+                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
                     });
                 }
                 catch (error) {
@@ -298,7 +302,7 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
 Use ONLY when you don't have a page ID. IMPORTANT: Use the space KEY (e.g. 'MESH', 'TC'), NOT the space name.
 
 Returns pageId, version, bufferId, and structure (element IDs) for structured editing.
-Use buffer_edit with element IDs to modify, then confluence_draft_create for user review.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.`,
             inputSchema: z.object({
                 spaceKey: z.string().describe("Space key (short code like 'MESH', 'TC'), NOT the full space name"),
                 title: z.string().describe("Page title"),
@@ -314,7 +318,9 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                             statusCode: 404,
                         });
                     }
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -331,7 +337,196 @@ Use buffer_edit with element IDs to modify, then confluence_draft_create for use
                         bufferId,
                         ...(structure && { structure }),
                         contentSize: content.length,
-                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create for user review.",
+                        message: "Page loaded. Use buffer_edit to modify, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_edit: {
+            description: `Smart page/draft loader - auto-resolves URLs, pageIds, draftIds, or SPACE/Title.
+
+ACCEPTS ANY OF:
+  - Full URL: https://confluence.example.com/pages/viewpage.action?pageId=123
+  - Full URL: https://confluence.example.com/pages/resumedraft.action?draftId=456
+  - Full URL: https://confluence.example.com/display/SPACE/Page+Title
+  - Page ID: "123456"
+  - Draft ID: "draft:123456" (prefix with "draft:")
+  - Space/Title: "DOCS/API Guide"
+
+SMART BEHAVIOR:
+  - URLs are parsed automatically to extract pageId or draftId
+  - Draft IDs: tries to load draft; if 404 (published), finds page by title
+  - Returns bufferId + structure + pageId for editing
+
+WORKFLOW:
+  1. confluence_edit(input) → bufferId, structure, pageId
+  2. buffer_edit(bufferId, ...) → modify content
+  3. confluence_draft_create(pageId=..., bufferId=...) → draft linked to original page
+  4. User publishes via Confluence UI (updates original page)
+  5. For more edits: confluence_edit(same URL or "SPACE/Title") → auto-resolves`,
+            inputSchema: z.object({
+                input: z.string().describe('URL, pageId, "draft:ID", or "SPACE/Title"'),
+            }),
+            handler: async (args) => {
+                const input = args.input.trim();
+                if (!input) {
+                    return formatError({
+                        error: true,
+                        message: "Input is required. Provide a URL, pageId, draft:ID, or SPACE/Title.",
+                        statusCode: 400,
+                    });
+                }
+                // Helper to load page content and return formatted result
+                const loadPageContent = async (pageResult) => {
+                    const rawContent = pageResult.body?.storage?.value || "";
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
+                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
+                        resourceType: "confluence_page",
+                        resourceId: String(pageResult.id),
+                        contentType: "xhtml",
+                        version: pageResult.version?.number,
+                        spaceKey: pageResult.space?.key,
+                        title: pageResult.title,
+                    });
+                    return {
+                        pageId: pageResult.id,
+                        spaceKey: pageResult.space?.key,
+                        title: pageResult.title,
+                        version: pageResult.version?.number,
+                        bufferId,
+                        structure,
+                        contentSize: content.length,
+                        message: "Content loaded. Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to add content, then confluence_draft_create(pageId=..., bufferId=...) for user review.",
+                    };
+                };
+                // Helper to load draft content
+                const loadDraftContent = async (draftId) => {
+                    const result = await client.getDraft(draftId);
+                    const rawContent = result.body?.storage?.value || "";
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
+                    const { bufferId, structure } = storeXhtmlWithStructure(content, {
+                        resourceType: "confluence_page",
+                        resourceId: String(result.id),
+                        contentType: "xhtml",
+                        spaceKey: result.space?.key,
+                        title: result.title,
+                        isDraft: true,
+                    });
+                    return {
+                        draftId: result.id,
+                        spaceKey: result.space?.key,
+                        title: result.title,
+                        bufferId,
+                        structure,
+                        contentSize: content.length,
+                        message: "Draft loaded. Use buffer_edit to modify, then confluence_draft_save to update.",
+                    };
+                };
+                try {
+                    // Case 1: Full URL
+                    if (input.startsWith("http://") || input.startsWith("https://")) {
+                        const parsed = parseUrl(input);
+                        if (parsed.type === "confluence_page" && parsed.pageId) {
+                            const result = await client.getPage(parsed.pageId);
+                            return formatSuccess(await loadPageContent(result));
+                        }
+                        if (parsed.type === "confluence_draft" && parsed.draftId) {
+                            try {
+                                return formatSuccess(await loadDraftContent(parsed.draftId));
+                            }
+                            catch (error) {
+                                // Draft may have been published - try to find page by title
+                                if (isApiError(error) && error.statusCode === 404 && parsed.spaceKey && parsed.title) {
+                                    const pageResult = await client.getPageByTitle(parsed.spaceKey, parsed.title);
+                                    if (pageResult) {
+                                        return formatSuccess({
+                                            ...await loadPageContent(pageResult),
+                                            note: "Draft was published. Loaded the published page instead.",
+                                        });
+                                    }
+                                }
+                                throw error;
+                            }
+                        }
+                        if (parsed.type === "confluence_space_path" && parsed.spaceKey && parsed.title) {
+                            const pageResult = await client.getPageByTitle(parsed.spaceKey, parsed.title);
+                            if (!pageResult) {
+                                return formatError({
+                                    error: true,
+                                    message: `Page not found: "${parsed.title}" in space ${parsed.spaceKey}`,
+                                    statusCode: 404,
+                                });
+                            }
+                            return formatSuccess(await loadPageContent(pageResult));
+                        }
+                        return formatError({
+                            error: true,
+                            message: `Unable to parse URL: "${input}". Use Confluence page, draft, or display URL.`,
+                            statusCode: 400,
+                        });
+                    }
+                    // Case 2: Draft ID (prefix with "draft:")
+                    if (input.startsWith("draft:")) {
+                        const draftId = input.substring(6);
+                        try {
+                            return formatSuccess(await loadDraftContent(draftId));
+                        }
+                        catch (error) {
+                            if (isApiError(error) && error.statusCode === 404) {
+                                return formatError({
+                                    error: true,
+                                    message: `Draft ${draftId} not found. It may have been published. Try using the page URL or "SPACE/Title" format.`,
+                                    statusCode: 404,
+                                    details: {
+                                        hint: "If the draft was published, ask the user for the published page URL.",
+                                    },
+                                });
+                            }
+                            throw error;
+                        }
+                    }
+                    // Case 3: Space/Title format (e.g., "DOCS/API Guide")
+                    if (input.includes("/") && !input.match(/^\d+$/)) {
+                        const slashIndex = input.indexOf("/");
+                        const spaceKey = input.substring(0, slashIndex).trim();
+                        const title = input.substring(slashIndex + 1).trim();
+                        if (!spaceKey || !title) {
+                            return formatError({
+                                error: true,
+                                message: `Invalid SPACE/Title format: "${input}". Expected "SPACEKEY/Page Title".`,
+                                statusCode: 400,
+                            });
+                        }
+                        const pageResult = await client.getPageByTitle(spaceKey, title);
+                        if (!pageResult) {
+                            return formatError({
+                                error: true,
+                                message: `Page not found: "${title}" in space ${spaceKey}`,
+                                statusCode: 404,
+                            });
+                        }
+                        return formatSuccess(await loadPageContent(pageResult));
+                    }
+                    // Case 4: Pure numeric page ID
+                    if (/^\d+$/.test(input)) {
+                        const result = await client.getPage(input);
+                        return formatSuccess(await loadPageContent(result));
+                    }
+                    return formatError({
+                        error: true,
+                        message: `Unable to parse input: "${input}". Expected URL, pageId, "draft:ID", or "SPACE/Title".`,
+                        statusCode: 400,
+                        details: {
+                            examples: [
+                                "https://confluence.example.com/pages/viewpage.action?pageId=123",
+                                "123456 (page ID)",
+                                "draft:456789 (draft ID)",
+                                "DOCS/API Guide (space/title)",
+                            ],
+                        },
                     });
                 }
                 catch (error) {
@@ -521,22 +716,32 @@ Returns the user's personal space key and details. Use this to verify your perso
         confluence_draft_create: {
             description: `Create a Confluence draft for user review. Returns draftId, bufferId, structure (element IDs), and clickable URL.
 
+IMPORTANT: Call help(topic="plantuml") BEFORE creating content with PlantUML diagrams.
+IMPORTANT: Call help(topic="storage") BEFORE creating XHTML content for proper syntax.
 IMPORTANT: User must validate the draft in Confluence UI before publishing.
-IMPORTANT: Raw @startuml outside macros is NOT supported. Use buffer_edit for auto-wrapping, or embed properly formatted ac:structured-macro elements.
+IMPORTANT: Raw @startuml outside macros is NOT supported. Use buffer_edit with plantuml parameter.
 
-TIP: See help(topic="storage") for XHTML syntax, help(topic="plantuml") for diagrams.
+Two modes:
+1. NEW PAGE: Provide spaceKey + title + content/bufferId → creates standalone draft
+2. EDIT EXISTING PAGE (Review Workflow): Provide pageId + bufferId
+   - Creates "[jicon-mcp REVIEW] Title" draft linked to original via label
+   - REQUIRED: bufferId must come from confluence_get_page(pageId) or confluence_edit(pageId)
+   - Use confluence_review_publish(draftId) to apply changes to original
+   - Use confluence_review_discard(draftId) to cancel without changes
+   - Use confluence_review_list() to find all review drafts
 
-Workflow:
-1. Create draft with this tool → returns URL and structure with element IDs
-2. User reviews draft in Confluence UI (can edit there)
-3. If user requests changes: use confluence_draft_open to get user's edits
-4. Modify with buffer_edit using element IDs, then confluence_draft_save for new review
-5. User publishes manually via Confluence UI
+Workflow for editing existing page:
+1. confluence_get_page(pageId) → bufferId, structure
+2. buffer_edit(bufferId, ...) → modify content
+3. confluence_draft_create(pageId=..., bufferId=...) → creates review draft
+4. User reviews in Confluence UI
+5. confluence_review_publish(draftId) → applies changes to original page
 
 Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit).`,
             inputSchema: z.object({
-                spaceKey: z.string().describe("Space key"),
-                title: z.string().describe("Page title"),
+                pageId: z.coerce.string().optional().describe("Existing page ID to create edit draft for. When provided, bufferId must come from that page."),
+                spaceKey: z.string().optional().describe("Space key (required for new pages, auto-populated when pageId is provided)"),
+                title: z.string().optional().describe("Page title (required for new pages, auto-populated when pageId is provided)"),
                 content: z
                     .string()
                     .optional()
@@ -546,6 +751,83 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                 labels: z.array(z.string()).optional().describe("Array of labels"),
             }),
             handler: async (args) => {
+                // Determine the mode: editing existing page vs creating new draft
+                let spaceKey = args.spaceKey;
+                let title = args.title;
+                let parentId = args.parentId;
+                let originalPageId;
+                let originalPageVersion;
+                if (args.pageId) {
+                    // MODE: Edit existing page - validate bufferId came from this page
+                    if (!args.bufferId) {
+                        return formatError({
+                            error: true,
+                            message: "When pageId is provided, bufferId is required (must come from confluence_get_page or confluence_edit of that page)",
+                            statusCode: 400,
+                            details: {
+                                hint: "First call confluence_get_page(pageId) or confluence_edit(pageId) to get a bufferId, then modify with buffer_edit",
+                            },
+                        });
+                    }
+                    // Validate buffer originated from the specified page
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    const bufferSourceId = bufferInfo.metadata?.resourceId;
+                    if (bufferSourceId !== args.pageId) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer '${args.bufferId}' does not belong to page '${args.pageId}'`,
+                            statusCode: 400,
+                            details: {
+                                bufferSource: bufferSourceId || "unknown",
+                                expectedPage: args.pageId,
+                                hint: "Two options: (1) Load page first with confluence_edit(pageId) then use buffer_edit to modify, OR (2) If you already created content in a separate buffer, use buffer_edit(pageBufferId, after=N, fromBufferId=yourNewBuffer) to merge it into the page buffer",
+                            },
+                        });
+                    }
+                    // Fetch original page info to get space, title, parent, etc.
+                    try {
+                        const originalPage = await client.getPage(args.pageId, ["space", "ancestors", "version"]);
+                        spaceKey = originalPage.space?.key;
+                        title = args.title || originalPage.title; // Allow title override
+                        originalPageId = originalPage.id;
+                        originalPageVersion = originalPage.version?.number;
+                        // Get parent from ancestors if not explicitly provided
+                        if (!parentId && originalPage.ancestors && originalPage.ancestors.length > 0) {
+                            parentId = originalPage.ancestors[originalPage.ancestors.length - 1].id;
+                        }
+                        if (!spaceKey) {
+                            return formatError({
+                                error: true,
+                                message: `Could not determine space key for page ${args.pageId}`,
+                                statusCode: 400,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to fetch original page ${args.pageId}: ${error instanceof Error ? error.message : String(error)}`,
+                            statusCode: 404,
+                        });
+                    }
+                }
+                else {
+                    // MODE: New page - require spaceKey and title
+                    if (!spaceKey || !title) {
+                        return formatError({
+                            error: true,
+                            message: "For new drafts, both 'spaceKey' and 'title' are required. For editing existing pages, provide 'pageId' instead.",
+                            statusCode: 400,
+                        });
+                    }
+                }
                 // Resolve content from either content string or bufferId
                 const resolved = resolveContentFromBuffer(args.content, args.bufferId);
                 if (resolved.error) {
@@ -580,14 +862,66 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                 // Expand PlantUML !include directives before sending to Confluence
                 const expandedContent = await expandPlantUmlInXhtml(content);
                 try {
-                    const result = await client.createDraft({
-                        spaceKey: args.spaceKey,
-                        title: args.title,
-                        content: expandedContent,
-                        parentId: args.parentId,
-                        labels: args.labels,
-                    });
+                    // Constants for review workflow
+                    const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                    const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                    let result;
+                    let existingReviewDraft = null;
+                    let reviewLabel;
+                    if (originalPageId) {
+                        // REVIEW WORKFLOW: Creating/updating review draft for existing page
+                        reviewLabel = `${REVIEW_LABEL_PREFIX}${originalPageId}`;
+                        // Check if review draft already exists for this page
+                        existingReviewDraft = await client.findDraftByLabel(reviewLabel);
+                        if (existingReviewDraft) {
+                            // Delete existing review draft to update it (API doesn't support draft updates)
+                            await client.deleteDraft(existingReviewDraft.id);
+                        }
+                        // Prevent nested review drafts
+                        const reviewTitle = title.startsWith(REVIEW_PREFIX)
+                            ? title
+                            : `${REVIEW_PREFIX}${title}`;
+                        // Create review draft with label linking to original page
+                        const labels = [...(args.labels || []), reviewLabel];
+                        result = await client.createDraft({
+                            spaceKey: spaceKey,
+                            title: reviewTitle,
+                            content: expandedContent,
+                            parentId: parentId,
+                            labels: labels,
+                        });
+                    }
+                    else {
+                        // NEW PAGE MODE: Create standalone draft
+                        result = await client.createDraft({
+                            spaceKey: spaceKey,
+                            title: title,
+                            content: expandedContent,
+                            parentId: parentId,
+                            labels: args.labels,
+                        });
+                    }
+                    // Verify draft is readable with labels (catches label attachment failures)
+                    if (originalPageId && reviewLabel) {
+                        const verifyDraft = await client.getDraft(result.id, [
+                            ...DEFAULT_PAGE_EXPAND,
+                            "metadata.labels",
+                        ]);
+                        const labels = verifyDraft.metadata?.labels?.results || [];
+                        const hasReviewLabel = labels.some((l) => l.name === reviewLabel);
+                        if (!hasReviewLabel) {
+                            // Label attachment may have failed - try to add it again
+                            // This can happen due to eventual consistency or API timing
+                            try {
+                                await client.addLabels(result.id, [reviewLabel], true);
+                            }
+                            catch {
+                                // If label add fails, warn but continue (draft still exists)
+                            }
+                        }
+                    }
                     // Store content with element IDs for structured editing
+                    // Track originalPageId in metadata so we can link the draft to its source
                     const { bufferId: newBufferId } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
                         resourceId: result.id,
@@ -595,13 +929,16 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                         spaceKey: result.space?.key,
                         title: result.title,
                         isDraft: true,
+                        originalPageId: originalPageId,
+                        originalPageVersion: originalPageVersion,
                     });
                     // Build the draft edit URL (drafts use resumedraft.action, not the webui link)
                     const baseUrl = client.getBaseUrl();
                     const draftUrl = `${baseUrl}/pages/resumedraft.action?draftId=${result.id}`;
                     // Generate content summary for verification
                     const summary = getContentSummary(content);
-                    return formatSuccess({
+                    // Build response with original page info if editing existing page
+                    const response = {
                         draftId: result.id,
                         bufferId: newBufferId,
                         title: result.title,
@@ -616,11 +953,37 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
                             hasTable: summary.hasTable,
                             headings: summary.headingCount,
                         },
-                        message: "Draft created. IMPORTANT: Display the URL above to the user so they can review and publish.",
-                        ...(summary.plantumlCount === 0 && {
-                            warning: "No PlantUML diagrams found in content. If diagrams were expected, use buffer_edit with plantuml parameter.",
-                        }),
-                    });
+                    };
+                    // Add review workflow info when editing existing page
+                    if (originalPageId) {
+                        response.reviewDraft = {
+                            originalPageId: originalPageId,
+                            originalPageVersion: originalPageVersion,
+                            reviewLabel: reviewLabel,
+                            wasUpdated: !!existingReviewDraft,
+                            note: "This is a REVIEW draft linked to the original page.",
+                        };
+                        response.message = existingReviewDraft
+                            ? `Review draft updated for page ${originalPageId}. Use confluence_review_publish(${result.id}) to apply changes.`
+                            : `Review draft created for page ${originalPageId}. Use confluence_review_publish(${result.id}) to apply changes.`;
+                        response.nextSteps = {
+                            toPublish: `confluence_review_publish(reviewDraftId="${result.id}")`,
+                            toDiscard: `confluence_review_discard(reviewDraftId="${result.id}")`,
+                            toList: "confluence_review_list()",
+                        };
+                    }
+                    else {
+                        response.message = "Draft created. IMPORTANT: Display the URL above to the user so they can review and publish.";
+                        response.afterPublish = {
+                            note: "After user publishes, the draft ID becomes invalid.",
+                            editAgain: `confluence_edit("${result.space?.key}/${result.title}")`,
+                            tip: "Use confluence_edit with the same SPACE/Title or page URL to edit the published page.",
+                        };
+                    }
+                    if (summary.plantumlCount === 0) {
+                        response.warning = "No PlantUML diagrams found in content. If diagrams were expected, use buffer_edit with plantuml parameter.";
+                    }
+                    return formatSuccess(response);
                 }
                 catch (error) {
                     // Try to enhance XHTML errors with location info for targeted fixes
@@ -637,14 +1000,16 @@ Provide either 'content' (string) OR 'bufferId' (from buffer_create/buffer_edit)
         confluence_draft_open: {
             description: `Open an existing draft page for editing. Loads content into buffer with structure (element IDs).
 
-Use buffer_edit with element IDs to modify content, then confluence_draft_save. User publishes via Confluence UI.`,
+Use buffer_edit(bufferId, after=ID, content/plantuml/fromBufferId) to modify, then confluence_draft_save. User publishes via Confluence UI.`,
             inputSchema: z.object({
                 draftId: z.coerce.string().describe("Draft page ID"),
             }),
             handler: async (args) => {
                 try {
                     const result = await client.getDraft(args.draftId);
-                    const content = result.body?.storage?.value || "";
+                    const rawContent = result.body?.storage?.value || "";
+                    // Collapse expanded includes back to !include directives
+                    const content = collapseExpandedIncludesInXhtml(rawContent);
                     // Store content with element IDs for structured editing
                     const { bufferId, structure } = storeXhtmlWithStructure(content, {
                         resourceType: "confluence_page",
@@ -859,6 +1224,195 @@ Drafts are NOT sent to trash - they are permanently deleted.`,
                 }
             },
         },
+        // ========================================
+        // Review Workflow Tools
+        // ========================================
+        // These tools manage the "[jicon-mcp REVIEW]" workflow for editing existing pages.
+        // Review drafts are linked to original pages via labels and can be published
+        // to apply changes to the original page.
+        confluence_review_publish: {
+            description: `Publish a review draft to apply changes to the original page.
+
+This tool:
+1. Validates the draft is a "[jicon-mcp REVIEW]" draft with proper label
+2. Copies the draft content to the original page (creates new version)
+3. Deletes the review draft
+
+Use this after user has reviewed the draft in Confluence UI.`,
+            inputSchema: z.object({
+                reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to publish"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                try {
+                    // 1. Get review draft with labels
+                    const reviewDraft = await client.getDraft(args.reviewDraftId, [
+                        ...DEFAULT_PAGE_EXPAND,
+                        "metadata.labels",
+                    ]);
+                    // 2. Validate it's a review draft
+                    if (!reviewDraft.title.startsWith(REVIEW_PREFIX)) {
+                        return formatError({
+                            error: true,
+                            message: `Not a jicon review draft. Title must start with "${REVIEW_PREFIX}"`,
+                            statusCode: 400,
+                            details: {
+                                actualTitle: reviewDraft.title,
+                                hint: "Use confluence_draft_create with pageId to create a review draft",
+                            },
+                        });
+                    }
+                    // 3. Find original page from label
+                    const labels = reviewDraft.metadata?.labels?.results || [];
+                    const reviewLabel = labels.find((l) => l.name.startsWith(REVIEW_LABEL_PREFIX));
+                    if (!reviewLabel) {
+                        return formatError({
+                            error: true,
+                            message: "Review draft missing link to original page (no jicon-review-* label found)",
+                            statusCode: 400,
+                            details: {
+                                labels: labels.map((l) => l.name),
+                                hint: "This draft may have been created manually. Use confluence_draft_create with pageId to create proper review drafts.",
+                            },
+                        });
+                    }
+                    const originalPageId = reviewLabel.name.replace(REVIEW_LABEL_PREFIX, '');
+                    // 4. Fetch original page to get current version
+                    let originalPage;
+                    try {
+                        originalPage = await client.getPage(originalPageId, ["version", "space"]);
+                    }
+                    catch (error) {
+                        return formatError({
+                            error: true,
+                            message: `Original page ${originalPageId} not found. It may have been deleted.`,
+                            statusCode: 404,
+                            details: {
+                                originalPageId,
+                                hint: "If the original page was deleted, use confluence_review_discard to remove this review draft.",
+                            },
+                        });
+                    }
+                    // 5. Get the review draft content
+                    const reviewContent = reviewDraft.body?.storage?.value || "";
+                    // 6. Update original page with review content
+                    const updatedPage = await client.updatePage(originalPageId, originalPage.version?.number || 1, originalPage.title, // Keep original title (not the REVIEW prefix)
+                    reviewContent, false // Not a minor edit
+                    );
+                    // 7. Delete review draft
+                    await client.deleteDraft(args.reviewDraftId);
+                    // 8. Invalidate buffers
+                    contentBuffer.invalidateByMetadata({ resourceId: originalPageId });
+                    contentBuffer.invalidateByMetadata({ resourceId: args.reviewDraftId });
+                    // Build the page URL
+                    const baseUrl = client.getBaseUrl();
+                    const pageUrl = `${baseUrl}${updatedPage._links?.webui || `/pages/viewpage.action?pageId=${originalPageId}`}`;
+                    return formatSuccess({
+                        success: true,
+                        originalPageId,
+                        originalTitle: updatedPage.title,
+                        newVersion: updatedPage.version?.number,
+                        reviewDraftDeleted: args.reviewDraftId,
+                        viewUrl: pageUrl,
+                        message: `Changes from review draft applied to page "${updatedPage.title}" (version ${updatedPage.version?.number}). Review draft deleted.`,
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_review_discard: {
+            description: `Discard a review draft without applying changes to the original page.
+
+This tool:
+1. Validates the draft is a "[jicon-mcp REVIEW]" draft
+2. Deletes the review draft permanently
+3. Original page remains unchanged`,
+            inputSchema: z.object({
+                reviewDraftId: z.coerce.string().describe("ID of the [jicon-mcp REVIEW] draft to discard"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                try {
+                    // 1. Get review draft to validate
+                    const reviewDraft = await client.getDraft(args.reviewDraftId);
+                    // 2. Validate it's a review draft
+                    if (!reviewDraft.title.startsWith(REVIEW_PREFIX)) {
+                        return formatError({
+                            error: true,
+                            message: `Not a jicon review draft. Title must start with "${REVIEW_PREFIX}"`,
+                            statusCode: 400,
+                            details: {
+                                actualTitle: reviewDraft.title,
+                                hint: "Use confluence_draft_delete for non-review drafts",
+                            },
+                        });
+                    }
+                    // 3. Delete review draft
+                    await client.deleteDraft(args.reviewDraftId);
+                    // 4. Invalidate buffer
+                    contentBuffer.invalidateByMetadata({ resourceId: args.reviewDraftId });
+                    return formatSuccess({
+                        success: true,
+                        discarded: true,
+                        reviewDraftId: args.reviewDraftId,
+                        originalTitle: reviewDraft.title.replace(REVIEW_PREFIX, ''),
+                        message: "Review draft discarded. Original page was not modified.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
+        confluence_review_list: {
+            description: `List all "[jicon-mcp REVIEW]" drafts for cleanup or management.
+
+Returns review drafts with their linked original page IDs.
+Use this to find abandoned review drafts or manage multiple review workflows.`,
+            inputSchema: z.object({
+                spaceKey: z.string().optional().describe("Filter by space key (optional)"),
+            }),
+            handler: async (args) => {
+                const REVIEW_PREFIX = '[jicon-mcp REVIEW] ';
+                const REVIEW_LABEL_PREFIX = 'jicon-review-';
+                try {
+                    // 1. List user's drafts with labels expanded
+                    const drafts = await client.listUserDrafts(args.spaceKey, 500);
+                    // 2. Filter to review drafts only
+                    const reviewDrafts = drafts.results.filter((draft) => draft.title?.startsWith(REVIEW_PREFIX));
+                    // 3. Build response with original page info from labels
+                    const baseUrl = client.getBaseUrl();
+                    const reviews = reviewDrafts.map((draft) => {
+                        const labels = draft.metadata?.labels?.results || [];
+                        const reviewLabel = labels.find((l) => l.name.startsWith(REVIEW_LABEL_PREFIX));
+                        const originalPageId = reviewLabel?.name.replace(REVIEW_LABEL_PREFIX, '') || 'unknown';
+                        return {
+                            reviewDraftId: draft.id,
+                            title: draft.title,
+                            originalTitle: draft.title.replace(REVIEW_PREFIX, ''),
+                            originalPageId,
+                            spaceKey: draft.space?.key || '',
+                            spaceName: draft.space?.name || '',
+                            createdDate: draft.version?.when || '',
+                            editUrl: `${baseUrl}/pages/resumedraft.action?draftId=${draft.id}`,
+                        };
+                    });
+                    return formatSuccess({
+                        reviewDrafts: reviews,
+                        total: reviews.length,
+                        message: reviews.length > 0
+                            ? `Found ${reviews.length} review draft(s). Use confluence_review_publish or confluence_review_discard to manage.`
+                            : "No review drafts found.",
+                    });
+                }
+                catch (error) {
+                    return formatError(isApiError(error) ? error : new Error(String(error)));
+                }
+            },
+        },
     };
 }
 //# sourceMappingURL=tools.js.map