@crypto512/jicon-mcp 0.7.1 → 1.0.1

package/dist/utils/buffer-tools.js

@@ -2,11 +2,16 @@
  * Buffer management tools for MCP Server
  *
  * Provides tools to retrieve chunks from buffered content,
- * list active buffers, clear buffers, search content, and edit content.
+ * list active buffers, clear buffers, search content, edit content,
+ * and save content to files.
  */
 import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
 import { contentBuffer } from "./content-buffer.js";
 import { formatSuccess, formatError, getMaxOutputSize } from "./response-formatter.js";
+import { BufferEditXhtmlSchema, parseXhtml, serializeXhtml, executeOperation, validateXhtml, validateXhtmlAsync, validatePlantUml, buildPlantUmlMacro, querySelector, updatePlantUmlInMacro, resolveSemanticPosition, findUnsupportedPseudo, } from "./xhtml/index.js";
+import { validate as validatePlantUmlWithDocker, isAvailable as isPlantUmlServiceAvailable } from "./plantuml/service.js";
 /**
  * Format grep results as text output similar to grep CLI
  */
@@ -48,8 +53,65 @@ function formatGrepOutput(result, showLineNumbers) {
     }
     return lines.join("\n");
 }
+/**
+ * Find project root by walking up directory tree looking for .jicon.json
+ */
+function findProjectRoot() {
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+        if (fs.existsSync(path.join(dir, ".jicon.json"))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    // Fallback to cwd if no marker found
+    return process.cwd();
+}
+/**
+ * Check if content type indicates binary data that needs base64 decoding
+ */
+function isBinaryContentType(contentType) {
+    if (typeof contentType !== "string")
+        return false;
+    return [
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "image/webp",
+        "application/postscript",
+        "application/octet-stream",
+    ].some((type) => contentType.includes(type));
+}
 export function createBufferTools() {
     return {
+        buffer_create: {
+            description: `Create a new buffer with initial content. Use this to draft new content (e.g., for new Confluence pages) before persisting. Returns bufferId for use with buffer_edit and other buffer tools.`,
+            inputSchema: z.object({
+                content: z.string().describe("Initial content for the buffer"),
+                metadata: z
+                    .record(z.unknown())
+                    .optional()
+                    .describe("Optional metadata to attach to the buffer"),
+            }),
+            handler: async (args) => {
+                try {
+                    const bufferId = contentBuffer.store(args.content, args.metadata);
+                    const info = contentBuffer.getInfo(bufferId);
+                    return formatSuccess({
+                        bufferId,
+                        totalSize: info?.totalSize ?? args.content.length,
+                        createdAt: info ? new Date(info.createdAt).toISOString() : new Date().toISOString(),
+                        expiresAt: info ? new Date(info.expiresAt).toISOString() : undefined,
+                        metadata: args.metadata,
+                        message: "Buffer created. Use buffer_edit to modify, buffer_get_chunk to read.",
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
         buffer_get_chunk: {
             description: `Retrieve a chunk of buffered content by buffer ID. Use after receiving a bufferId from tools. Returns content, offset, totalSize, and hasMore flag.`,
             inputSchema: z.object({
@@ -91,7 +153,18 @@ export function createBufferTools() {
             },
         },
         buffer_list: {
-            description: `List all active buffers with metadata. Buffers expire after 10 minutes.`,
+            description: `List all active buffers with metadata. Buffers expire after 10 minutes.
+
+Use to recover lost buffer IDs or find buffers associated with Confluence drafts.
+
+Metadata includes:
+- resourceType: "confluence_page" for Confluence content
+- resourceId: page/draft ID
+- isDraft: true for unsaved drafts
+- title, spaceKey: page info
+- contentType: "xhtml", "plain", or "json"
+
+Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345"`,
             inputSchema: z.object({}),
             handler: async () => {
                 try {
@@ -270,7 +343,9 @@ export function createBufferTools() {
             },
         },
         buffer_edit: {
-            description: `Exact string replacement in buffered content. Fails if old_string is not unique (use replace_all=true for all occurrences). Changes are in-memory only - call update API to persist.`,
+            description: `Exact string replacement in buffered content. Fails if old_string is not unique (use replace_all=true for all occurrences). Changes are in-memory only - call update API to persist.
+
+For Confluence content: Use buffer_edit_xhtml instead for structure-aware editing (tables, macros, layouts). Call help(topic="storage") for guide.`,
             inputSchema: z.object({
                 bufferId: z.string().describe("Buffer ID to modify"),
                 old_string: z.string().describe("Exact text to replace"),
@@ -283,6 +358,19 @@ export function createBufferTools() {
             }),
             handler: async (args) => {
                 try {
+                    // Check if buffer contains XHTML content - reject to force use of buffer_edit_xhtml
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (bufferInfo?.metadata?.contentType === "xhtml") {
+                        return formatError({
+                            error: true,
+                            message: "This buffer contains Confluence XHTML content. Use buffer_edit_xhtml instead for proper structure-aware editing.",
+                            statusCode: 400,
+                            details: {
+                                hint: "For PlantUML diagrams, use: buffer_edit_xhtml(bufferId, operation='insert-plantuml', ...)",
+                                contentType: "xhtml",
+                            },
+                        });
+                    }
                     const result = contentBuffer.edit(args.bufferId, args.old_string, args.new_string, args.replace_all ?? false);
                     if (!result) {
                         return formatError({
@@ -307,6 +395,525 @@ export function createBufferTools() {
                 }
             },
         },
+        buffer_edit_xhtml: {
+            description: `Structure-aware XHTML editing for Confluence storage format. Supports CSS-like selectors to target elements, with operations: insert, insert-plantuml, update, update-plantuml, remove, move, wrap.
+
+Selector syntax:
+- Tag: 'p', 'h1', 'table'
+- Namespaced: 'ac:structured-macro', 'ri:page'
+- Attributes: '[ac:name="plantuml"]', 'ac:structured-macro[ac:name="code"]'
+- Pseudo: ':nth-child(2)', ':first-child', ':last-child'
+- Descendants: 'table tbody tr'
+- Direct child: 'ul > li'
+
+Semantic positions (for insert-plantuml, alternative to selector):
+- 'after-title': After first h1 or h2
+- 'after-heading': After first heading (h1-h6)
+- 'before-content': At document start
+- 'end': At document end
+- 'after-toc': After table of contents macro
+
+PlantUML: Use plantuml_validate first for full Docker-based validation. This tool uses basic sync validation.`,
+            inputSchema: BufferEditXhtmlSchema,
+            handler: async (args) => {
+                try {
+                    // Get buffer content
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                    if (!chunk) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to read buffer: ${args.bufferId}`,
+                            statusCode: 500,
+                        });
+                    }
+                    const originalContent = chunk.chunk;
+                    const oldSize = originalContent.length;
+                    // Parse XHTML
+                    const parseResult = parseXhtml(originalContent);
+                    if (!parseResult.document) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to parse XHTML: ${parseResult.error?.message}`,
+                            statusCode: 400,
+                            details: {
+                                parseError: parseResult.error?.message,
+                                line: parseResult.error?.line,
+                                column: parseResult.error?.column,
+                                context: parseResult.error?.context,
+                                hint: parseResult.error?.context
+                                    ? `Check near: "${parseResult.error.context.substring(0, 60)}${parseResult.error.context.length > 60 ? "..." : ""}"`
+                                    : undefined,
+                            },
+                        });
+                    }
+                    // Handle PlantUML operations specially
+                    let contentToInsert = args.content;
+                    const operation = args.operation;
+                    let resolvedSelector = args.selector;
+                    let resolvedPosition = args.position;
+                    let insertDiagramType; // Track diagram type for insert-plantuml
+                    // Check if we need to derive selector from semanticPosition
+                    if (!resolvedSelector && args.semanticPosition) {
+                        const resolved = resolveSemanticPosition(parseResult.document, args.semanticPosition);
+                        if (resolved) {
+                            resolvedSelector = resolved.selector;
+                            resolvedPosition = resolved.position;
+                        }
+                        else {
+                            return formatError({
+                                error: true,
+                                message: `Could not resolve semantic position: ${args.semanticPosition}`,
+                                statusCode: 400,
+                                details: {
+                                    semanticPosition: args.semanticPosition,
+                                    hint: "Document may be empty or missing required elements",
+                                },
+                            });
+                        }
+                    }
+                    // Check that we have a selector (either provided or derived from semanticPosition)
+                    if (!resolvedSelector) {
+                        return formatError({
+                            error: true,
+                            message: "Either selector or semanticPosition is required",
+                            statusCode: 400,
+                            details: {
+                                hint: "Provide selector (e.g., 'h1', 'table', 'ac:structured-macro[ac:name=\"plantuml\"]') or semanticPosition (e.g., 'after-title', 'end')",
+                            },
+                        });
+                    }
+                    if (operation === "insert-plantuml") {
+                        if (!args.plantuml) {
+                            return formatError({
+                                error: true,
+                                message: "plantuml parameter is required for insert-plantuml operation",
+                                statusCode: 400,
+                            });
+                        }
+                        // Validate PlantUML - use Docker service if available, else fallback to basic validation
+                        let normalizedCode;
+                        if (isPlantUmlServiceAvailable()) {
+                            // Use Docker-based validation
+                            try {
+                                const dockerValidation = await validatePlantUmlWithDocker(args.plantuml);
+                                if (!dockerValidation.valid) {
+                                    return formatError({
+                                        error: true,
+                                        message: "PlantUML syntax error",
+                                        statusCode: 400,
+                                        details: {
+                                            plantumlErrors: dockerValidation.errors,
+                                            diagramType: dockerValidation.diagramType,
+                                            hint: "Check plantuml_validate for detailed error info",
+                                        },
+                                    });
+                                }
+                                normalizedCode = dockerValidation.normalizedCode;
+                                insertDiagramType = dockerValidation.diagramType;
+                            }
+                            catch (error) {
+                                // Docker error - fallback to basic validation
+                                const basicValidation = validatePlantUml(args.plantuml);
+                                if (!basicValidation.valid) {
+                                    return formatError({
+                                        error: true,
+                                        message: "PlantUML syntax error",
+                                        statusCode: 400,
+                                        details: {
+                                            plantumlError: basicValidation.error,
+                                        },
+                                    });
+                                }
+                                normalizedCode = basicValidation.normalizedCode;
+                                insertDiagramType = basicValidation.diagramType;
+                            }
+                        }
+                        else {
+                            // Use basic synchronous validation
+                            const basicValidation = validatePlantUml(args.plantuml);
+                            if (!basicValidation.valid) {
+                                return formatError({
+                                    error: true,
+                                    message: "PlantUML syntax error",
+                                    statusCode: 400,
+                                    details: {
+                                        plantumlError: basicValidation.error,
+                                        hint: "Use plantuml_validate for full Docker-based validation",
+                                    },
+                                });
+                            }
+                            normalizedCode = basicValidation.normalizedCode;
+                            insertDiagramType = basicValidation.diagramType;
+                        }
+                        // Build the macro
+                        contentToInsert = buildPlantUmlMacro(normalizedCode, args.macroId);
+                    }
+                    else if (operation === "update-plantuml") {
+                        if (!args.plantuml) {
+                            return formatError({
+                                error: true,
+                                message: "plantuml parameter is required for update-plantuml operation",
+                                statusCode: 400,
+                            });
+                        }
+                        // Validate PlantUML - use Docker service if available, else fallback to basic validation
+                        let normalizedCode;
+                        let updateDiagramType;
+                        if (isPlantUmlServiceAvailable()) {
+                            // Use Docker-based validation
+                            try {
+                                const dockerValidation = await validatePlantUmlWithDocker(args.plantuml);
+                                if (!dockerValidation.valid) {
+                                    return formatError({
+                                        error: true,
+                                        message: "PlantUML syntax error",
+                                        statusCode: 400,
+                                        details: {
+                                            plantumlErrors: dockerValidation.errors,
+                                            diagramType: dockerValidation.diagramType,
+                                            hint: "Check plantuml_validate for detailed error info",
+                                        },
+                                    });
+                                }
+                                normalizedCode = dockerValidation.normalizedCode;
+                                updateDiagramType = dockerValidation.diagramType;
+                            }
+                            catch (error) {
+                                // Docker error - fallback to basic validation
+                                const basicValidation = validatePlantUml(args.plantuml);
+                                if (!basicValidation.valid) {
+                                    return formatError({
+                                        error: true,
+                                        message: "PlantUML syntax error",
+                                        statusCode: 400,
+                                        details: {
+                                            plantumlError: basicValidation.error,
+                                        },
+                                    });
+                                }
+                                normalizedCode = basicValidation.normalizedCode;
+                                updateDiagramType = basicValidation.diagramType;
+                            }
+                        }
+                        else {
+                            // Use basic synchronous validation
+                            const basicValidation = validatePlantUml(args.plantuml);
+                            if (!basicValidation.valid) {
+                                return formatError({
+                                    error: true,
+                                    message: "PlantUML syntax error",
+                                    statusCode: 400,
+                                    details: {
+                                        plantumlError: basicValidation.error,
+                                        hint: "Use plantuml_validate for full Docker-based validation",
+                                    },
+                                });
+                            }
+                            normalizedCode = basicValidation.normalizedCode;
+                            updateDiagramType = basicValidation.diagramType;
+                        }
+                        // Find the macro element and update it directly
+                        const selectorResult = querySelector(parseResult.document, args.selector);
+                        if (selectorResult.matches.length === 0) {
+                            const unsupportedPseudo = findUnsupportedPseudo(args.selector);
+                            const hint = unsupportedPseudo
+                                ? `Pseudo-selector ':${unsupportedPseudo}' is not supported. Use ':contains("text")' to find elements by text content, or use 'ac:structured-macro[ac:name="plantuml"]' with matchIndex.`
+                                : "Use 'ac:structured-macro[ac:name=\"plantuml\"]' to find PlantUML macros, or use matchIndex if multiple exist.";
+                            return formatError({
+                                error: true,
+                                message: `No elements match selector: ${args.selector}`,
+                                statusCode: 400,
+                                details: { selector: args.selector, matchCount: 0, hint },
+                            });
+                        }
+                        const targetIndex = args.matchIndex ?? 0;
+                        if (targetIndex >= selectorResult.matches.length) {
+                            return formatError({
+                                error: true,
+                                message: `matchIndex ${targetIndex} out of range (${selectorResult.matches.length} matches)`,
+                                statusCode: 400,
+                            });
+                        }
+                        const macroElement = selectorResult.matches[targetIndex].element;
+                        // Verify it's a plantuml macro
+                        if (macroElement.tagName.toLowerCase() !== "ac:structured-macro" ||
+                            macroElement.getAttribute("ac:name") !== "plantuml") {
+                            return formatError({
+                                error: true,
+                                message: "Selected element is not a PlantUML macro",
+                                statusCode: 400,
+                            });
+                        }
+                        // Update the macro content
+                        const updated = updatePlantUmlInMacro(macroElement, normalizedCode);
+                        if (!updated) {
+                            return formatError({
+                                error: true,
+                                message: "Failed to update PlantUML macro content",
+                                statusCode: 500,
+                            });
+                        }
+                        // Serialize and update buffer
+                        const newContent = serializeXhtml(parseResult.document);
+                        // Validate if requested
+                        if (args.validate !== false) {
+                            const validationResult = validateXhtml(newContent);
+                            if (!validationResult.valid) {
+                                const firstError = validationResult.errors[0];
+                                return formatError({
+                                    error: true,
+                                    message: `Resulting XHTML is invalid: ${firstError?.message || "Unknown error"}`,
+                                    statusCode: 400,
+                                    details: {
+                                        validationErrors: validationResult.errors,
+                                        hint: firstError?.location?.context
+                                            ? `Check near: "${firstError.location.context.substring(0, 60)}${firstError.location.context.length > 60 ? "..." : ""}"`
+                                            : undefined,
+                                    },
+                                });
+                            }
+                        }
+                        // Update buffer in place (keeps same buffer ID)
+                        contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" });
+                        return formatSuccess({
+                            bufferId: args.bufferId,
+                            success: true,
+                            operation: "update-plantuml",
+                            matchCount: 1,
+                            oldSize,
+                            newSize: newContent.length,
+                            affectedElements: ["ac:structured-macro"],
+                            diagramType: updateDiagramType,
+                        });
+                    }
+                    // Execute the operation
+                    const result = executeOperation(parseResult.document, operation, resolvedSelector, {
+                        position: resolvedPosition,
+                        content: contentToInsert,
+                        attributes: args.attributes,
+                        targetSelector: args.targetSelector,
+                        matchIndex: args.matchIndex,
+                        matchAll: args.matchAll,
+                    });
+                    if ("error" in result && result.error) {
+                        return formatError({
+                            error: true,
+                            message: result.message,
+                            statusCode: 400,
+                            details: result.details,
+                        });
+                    }
+                    // Serialize back to XHTML
+                    const newContent = serializeXhtml(parseResult.document);
+                    // Validate if requested
+                    if (args.validate !== false) {
+                        const validationResult = validateXhtml(newContent);
+                        if (!validationResult.valid) {
+                            const firstError = validationResult.errors[0];
+                            return formatError({
+                                error: true,
+                                message: `Resulting XHTML is invalid: ${firstError?.message || "Unknown error"}`,
+                                statusCode: 400,
+                                details: {
+                                    validationErrors: validationResult.errors,
+                                    hint: firstError?.location?.context
+                                        ? `Check near: "${firstError.location.context.substring(0, 60)}${firstError.location.context.length > 60 ? "..." : ""}"`
+                                        : undefined,
+                                },
+                            });
+                        }
+                    }
+                    // Update buffer in place (keeps same buffer ID)
+                    contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" });
+                    // Check if buffer is associated with a Confluence draft and add nextStep hint
+                    const updatedBufferInfo = contentBuffer.getInfo(args.bufferId);
+                    const isDraft = updatedBufferInfo?.metadata?.isDraft === true;
+                    const isConfluencePage = updatedBufferInfo?.metadata?.resourceType === "confluence_page";
+                    return formatSuccess({
+                        ...result,
+                        bufferId: args.bufferId,
+                        oldSize,
+                        newSize: newContent.length,
+                        ...(insertDiagramType && { diagramType: insertDiagramType }),
+                        ...((isDraft || isConfluencePage) && {
+                            nextStep: "Call confluence_draft_save(bufferId) to persist changes to Confluence",
+                        }),
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
+        buffer_validate_xhtml: {
+            description: `Validate buffered content as Confluence storage format (XHTML).
+
+Checks:
+- XML well-formedness (balanced tags, proper nesting)
+- Required attributes on Confluence elements (ac:name, ri:space-key, etc.)
+- Valid layout section types (single, two_equal, etc.)
+- Known macro names (warns for unknown macros)
+- PlantUML syntax (via Docker service, if running)
+
+PlantUML validation:
+- If Docker service is running, validates all PlantUML macros
+- If not running, adds warning (use plantuml_validate to start the service)
+
+Use this to validate content before calling confluence_update_page or confluence_create_page.`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID containing XHTML content"),
+                validatePlantUml: z
+                    .boolean()
+                    .optional()
+                    .default(true)
+                    .describe("Validate PlantUML syntax via Docker service (default: true)"),
+            }),
+            handler: async (args) => {
+                try {
+                    // Get buffer content
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                    if (!chunk) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to read buffer: ${args.bufferId}`,
+                            statusCode: 500,
+                        });
+                    }
+                    // Validate XHTML with async PlantUML validation
+                    const validationResult = await validateXhtmlAsync(chunk.chunk, {
+                        validatePlantUml: args.validatePlantUml !== false,
+                    });
+                    return formatSuccess({
+                        bufferId: args.bufferId,
+                        valid: validationResult.valid,
+                        errorCount: validationResult.errors.length,
+                        warningCount: validationResult.warnings.length,
+                        errors: validationResult.errors.map(e => ({
+                            type: e.type,
+                            message: e.message,
+                            location: e.location,
+                        })),
+                        warnings: validationResult.warnings.map(w => ({
+                            type: w.type,
+                            message: w.message,
+                            location: w.location,
+                        })),
+                        plantuml: validationResult.plantuml,
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
+        buffer_save_to_file: {
+            description: `Save buffer content to a file within the project directory.
+
+SECURITY: Files can only be saved within the project root (directory containing .jicon.json).
+Attempts to write outside this directory will be rejected.
+
+Binary handling:
+- If buffer metadata indicates binary content (image/png, application/postscript, etc.),
+  content is automatically decoded from base64
+- Use decodeBase64=true to force base64 decoding
+- PNG and EPS from plantuml_render are base64 encoded and will be auto-decoded
+
+Example:
+  buffer_save_to_file(bufferId="buf_xxx", outputPath="./diagrams/sequence.png")
+  buffer_save_to_file(bufferId="buf_yyy", outputPath="output/diagram.svg")`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID containing content to save"),
+                outputPath: z
+                    .string()
+                    .describe("Output file path relative to project root, or absolute path within project"),
+                decodeBase64: z
+                    .boolean()
+                    .optional()
+                    .describe("Force base64 decoding (auto-detected for binary content types like PNG/EPS)"),
+            }),
+            handler: async (args) => {
+                try {
+                    // 1. Validate buffer exists
+                    const info = contentBuffer.getInfo(args.bufferId);
+                    if (!info) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    // 2. Find project root
+                    const projectRoot = findProjectRoot();
+                    // 3. Resolve and validate output path
+                    const resolvedPath = path.resolve(projectRoot, args.outputPath);
+                    const normalizedProjectRoot = path.normalize(projectRoot);
+                    const normalizedOutputPath = path.normalize(resolvedPath);
+                    // Security check: ensure path is within project directory
+                    // Must start with projectRoot + separator, or be exactly projectRoot
+                    if (!normalizedOutputPath.startsWith(normalizedProjectRoot + path.sep) &&
+                        normalizedOutputPath !== normalizedProjectRoot) {
+                        return formatError({
+                            error: true,
+                            message: "Security: output path must be within project directory",
+                            statusCode: 403,
+                            details: {
+                                projectRoot: normalizedProjectRoot,
+                                requestedPath: normalizedOutputPath,
+                                hint: "Use a path relative to project root (e.g., './output/file.png')",
+                            },
+                        });
+                    }
+                    // 4. Get buffer content
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, info.totalSize);
+                    if (!chunk) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to read buffer: ${args.bufferId}`,
+                            statusCode: 500,
+                        });
+                    }
+                    // 5. Determine if base64 decoding needed
+                    const shouldDecode = args.decodeBase64 === true ||
+                        (args.decodeBase64 !== false &&
+                            isBinaryContentType(info.metadata?.contentType));
+                    // 6. Prepare content
+                    const content = shouldDecode
+                        ? Buffer.from(chunk.chunk, "base64")
+                        : Buffer.from(chunk.chunk, "utf-8");
+                    // 7. Ensure parent directory exists
+                    const parentDir = path.dirname(resolvedPath);
+                    await fs.promises.mkdir(parentDir, { recursive: true });
+                    // 8. Write file
+                    await fs.promises.writeFile(resolvedPath, content);
+                    return formatSuccess({
+                        success: true,
+                        path: resolvedPath,
+                        size: content.length,
+                        decoded: shouldDecode,
+                        message: `File saved successfully to ${resolvedPath}`,
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
     };
 }
 //# sourceMappingURL=buffer-tools.js.map