@crypto512/jicon-mcp 1.3.0 → 2.0.0

package/dist/utils/buffer-tools.js

@@ -2,18 +2,23 @@
  * Buffer management tools for MCP Server
  *
  * Provides tools to retrieve chunks from buffered content,
- * list active buffers, clear buffers, search content, edit content,
- * and save content to files.
+ * list active buffers, clear buffers, search content, and edit content.
  */
 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 { formatSuccess, formatSuccessDirect, formatError, getMaxOutputSize } from "./response-formatter.js";
+import { executePipelineWithOutput, validatePipeline, BufferPipelineInputSchema, } from "./buffer-pipeline/index.js";
+import { createJsonStructure } from "./json-structure.js";
 import { parseXhtml, serializeXhtml, validateXhtmlAsync, buildPlantUmlMacro, detectRawPlantUml, detectPlantUmlInContent, 
 // Element ID-based operations
 parseStructure, insertById, appendToDocument, replaceById, removeById, } from "./xhtml/index.js";
 import { validatePlantUmlWithFallback } from "./plantuml/index.js";
+/** Default maximum characters returned per chunk retrieval */
+const DEFAULT_CHUNK_SIZE = 5000;
+/** Maximum items returned per buffer_get_items call */
+const MAX_BATCH_ITEMS = 100;
+/** Default number of items returned per buffer_get_items call */
+const DEFAULT_BATCH_COUNT = 10;
 /**
  * Format grep results as text output similar to grep CLI
  */
@@ -56,47 +61,387 @@ function formatGrepOutput(result, showLineNumbers) {
     return lines.join("\n");
 }
 /**
- * Find project root by walking up directory tree looking for .jicon.json
+ * Validate buffer content type and return error if mismatch.
+ * Type-safe buffer access: tools should only accept buffers of the type they understand.
  */
-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;
+function validateBufferType(bufferId, expectedTypes, toolName) {
+    const bufferInfo = contentBuffer.getInfo(bufferId);
+    if (!bufferInfo) {
+        return {
+            error: true,
+            result: formatError({
+                error: true,
+                message: `Buffer not found: ${bufferId}`,
+                statusCode: 404,
+            }),
+        };
+    }
+    const actualType = bufferInfo.metadata?.contentType;
+    if (!expectedTypes.includes(actualType ?? "")) {
+        const typeHints = {
+            json: "Use buffer_pipeline for JSON data, or buffer_create(contentType='json') to create JSON buffers.",
+            xhtml: "Use buffer_create(contentType='xhtml') to create XHTML buffers, or confluence_get_page/confluence_edit to load Confluence content.",
+            plain: "Use buffer_create(contentType='plain') to create plain text buffers.",
+        };
+        const suggestedTools = {
+            json: "buffer_pipeline, buffer_get_items",
+            xhtml: "buffer_edit, buffer_get_structure, buffer_get_element, confluence_draft_create",
+            plain: "buffer_grep, buffer_get_chunk",
+        };
+        const hint = actualType ? typeHints[actualType] || "" : "";
+        const suggested = actualType ? suggestedTools[actualType] || "" : "";
+        return {
+            error: true,
+            result: formatError({
+                error: true,
+                message: `${toolName} requires ${expectedTypes.join(" or ")} buffer, but got: ${actualType || "unknown"}`,
+                statusCode: 400,
+                details: {
+                    bufferId,
+                    expectedTypes,
+                    actualType: actualType || "unknown",
+                    hint: hint || `Create a ${expectedTypes[0]} buffer first.`,
+                    suggestedTools: suggested ? `For ${actualType} buffers, use: ${suggested}` : undefined,
+                },
+            }),
+        };
+    }
+    return null; // Valid
+}
+/**
+ * Handle XHTML buffer editing with element IDs.
+ * Supports batch operations, PlantUML validation, and atomic rollback.
+ */
+async function handleXhtmlEdit(args, bufferInfo) {
+    // Build operations list: either from operations array or single operation params
+    let operations;
+    if (args.operations && args.operations.length > 0) {
+        // Batch mode: use operations array
+        operations = args.operations;
+    }
+    else {
+        // Single operation mode (backwards compatible)
+        const hasIdOperation = args.after !== undefined || args.before !== undefined ||
+            args.replace !== undefined || args.append || args.remove !== undefined;
+        if (!hasIdOperation) {
+            return formatError({
+                error: true,
+                message: "XHTML buffer requires element ID operation: after, before, replace, append, remove, or operations array",
+                statusCode: 400,
+                details: {
+                    structure: bufferInfo.structure,
+                    nextId: bufferInfo.nextId,
+                    hint: "Use after=ID, before=ID, replace=ID, append=true, remove=ID, or operations=[...]",
+                },
+            });
         }
-        dir = path.dirname(dir);
+        operations = [{
+                after: args.after,
+                before: args.before,
+                replace: args.replace,
+                append: args.append,
+                remove: args.remove,
+                content: args.content,
+                plantuml: args.plantuml,
+                fromBufferId: args.fromBufferId,
+            }];
+    }
+    // PHASE 0: Resolve fromBufferId to content for all operations
+    for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+        const op = operations[opIndex];
+        if (op.fromBufferId) {
+            // Validate source buffer exists
+            const sourceInfo = contentBuffer.getInfo(op.fromBufferId);
+            if (!sourceInfo) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: Source buffer '${op.fromBufferId}' not found or expired`,
+                    statusCode: 404,
+                });
+            }
+            // Get source buffer content
+            const sourceChunk = contentBuffer.getChunk(op.fromBufferId, 0, sourceInfo.bufferSizeBytes);
+            if (!sourceChunk) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: Failed to read source buffer '${op.fromBufferId}'`,
+                    statusCode: 500,
+                });
+            }
+            // Merge content: fromBufferId content takes precedence, but can be combined with plantuml
+            if (!op.content) {
+                op.content = sourceChunk.chunk;
+            }
+            else {
+                // If both content and fromBufferId, concatenate
+                op.content = op.content + sourceChunk.chunk;
+            }
+            // Clear fromBufferId since we've resolved it
+            delete op.fromBufferId;
+        }
+    }
+    // Get buffer content
+    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.bufferSizeBytes);
+    if (!chunk) {
+        return formatError({
+            error: true,
+            message: `Failed to read buffer: ${args.bufferId}`,
+            statusCode: 500,
+        });
     }
-    // Fallback to cwd if no marker found
-    return process.cwd();
+    // Parse XHTML once
+    const parseResult = parseXhtml(chunk.chunk);
+    if (!parseResult.document) {
+        return formatError({
+            error: true,
+            message: `Failed to parse XHTML: ${parseResult.error?.message}`,
+            statusCode: 400,
+        });
+    }
+    const oldSize = chunk.chunk.length;
+    let nextId = bufferInfo.nextId ?? 1;
+    const allInsertedIds = [];
+    const diagramTypes = [];
+    // PHASE 1: Check for PlantUML macros in content parameters (FORBIDDEN)
+    for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+        const op = operations[opIndex];
+        if (op.content) {
+            const plantUmlDetection = detectPlantUmlInContent(op.content);
+            if (plantUmlDetection) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: PlantUML macros in 'content' parameter are forbidden. Use 'plantuml' parameter for validated insertion.`,
+                    statusCode: 400,
+                    details: {
+                        operationIndex: opIndex,
+                        macrosFound: plantUmlDetection.count,
+                        hint: plantUmlDetection.hint,
+                    },
+                });
+            }
+        }
+    }
+    // PHASE 2: Pre-validate ALL PlantUML before any DOM mutations
+    const validatedPlantUml = new Map();
+    for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+        const op = operations[opIndex];
+        if (op.plantuml) {
+            const validation = await validatePlantUmlWithFallback(op.plantuml, "insert-plantuml", {});
+            if (!validation.valid) {
+                // Type-safe error extraction
+                let errorData = {
+                    error: true,
+                    message: "PlantUML validation failed",
+                    operationIndex: opIndex,
+                    completedOperations: 0,
+                    phase: "pre-validation",
+                };
+                // Safely extract error details if available
+                const errorObj = validation.error;
+                if (errorObj &&
+                    "content" in errorObj &&
+                    Array.isArray(errorObj.content) &&
+                    errorObj.content[0]?.text) {
+                    try {
+                        const parsed = JSON.parse(errorObj.content[0].text);
+                        errorData = {
+                            ...parsed,
+                            operationIndex: opIndex,
+                            completedOperations: 0,
+                            phase: "pre-validation",
+                        };
+                    }
+                    catch {
+                        // Keep default errorData if parsing fails
+                    }
+                }
+                return formatError({
+                    error: true,
+                    message: errorData.message || "PlantUML validation failed",
+                    statusCode: 400,
+                    details: errorData,
+                });
+            }
+            validatedPlantUml.set(opIndex, validation);
+        }
+    }
+    // PHASE 3: Execute operations (all PlantUML pre-validated)
+    // Note: Rollback is implicit - buffer is only updated after ALL operations succeed
+    for (let opIndex = 0; opIndex < operations.length; opIndex++) {
+        const op = operations[opIndex];
+        // Build content to insert (use pre-validated PlantUML)
+        let contentToInsert = op.content;
+        let diagramType;
+        if (op.plantuml) {
+            // Use pre-validated PlantUML (already validated in PHASE 2)
+            const validation = validatedPlantUml.get(opIndex);
+            contentToInsert = buildPlantUmlMacro(validation);
+            diagramType = validation.diagramType;
+            if (diagramType)
+                diagramTypes.push(diagramType);
+        }
+        // Execute single operation
+        let result;
+        if (op.remove !== undefined) {
+            result = removeById(parseResult.document, op.remove);
+        }
+        else if (op.replace !== undefined) {
+            if (!contentToInsert) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: content or plantuml required for replace operation`,
+                    statusCode: 400,
+                });
+            }
+            result = replaceById(parseResult.document, op.replace, contentToInsert);
+        }
+        else if (op.append) {
+            if (!contentToInsert) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: content or plantuml required for append operation`,
+                    statusCode: 400,
+                });
+            }
+            result = appendToDocument(parseResult.document, contentToInsert, nextId);
+            if (result.nextId)
+                nextId = result.nextId;
+        }
+        else if (op.after !== undefined) {
+            if (!contentToInsert) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: content or plantuml required for after operation`,
+                    statusCode: 400,
+                });
+            }
+            result = insertById(parseResult.document, op.after, "after", contentToInsert, nextId);
+            if (result.nextId)
+                nextId = result.nextId;
+        }
+        else if (op.before !== undefined) {
+            if (!contentToInsert) {
+                return formatError({
+                    error: true,
+                    message: `Operation ${opIndex + 1}: content or plantuml required for before operation`,
+                    statusCode: 400,
+                });
+            }
+            result = insertById(parseResult.document, op.before, "before", contentToInsert, nextId);
+            if (result.nextId)
+                nextId = result.nextId;
+        }
+        else {
+            return formatError({
+                error: true,
+                message: `Operation ${opIndex + 1}: No valid operation specified (need after, before, replace, append, or remove)`,
+                statusCode: 400,
+            });
+        }
+        if (!result.success) {
+            // Operation failed - buffer NOT updated (atomic rollback)
+            return formatError({
+                error: true,
+                message: `Operation ${opIndex + 1} failed: ${result.error || "Unknown error"}. Buffer unchanged (atomic rollback).`,
+                statusCode: 400,
+                details: {
+                    operationIndex: opIndex,
+                    completedOperations: 0, // No operations persisted due to rollback
+                    operation: op,
+                    structure: bufferInfo.structure,
+                    nextId: bufferInfo.nextId,
+                    rollback: true,
+                },
+            });
+        }
+        // Collect inserted IDs
+        if (result.insertedIds) {
+            allInsertedIds.push(...result.insertedIds);
+        }
+    }
+    // Serialize and update buffer once (after all operations)
+    const newContent = serializeXhtml(parseResult.document);
+    // Rebuild structure
+    const newStructure = parseStructure(parseResult.document);
+    // Update buffer
+    contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" }, newStructure.structure, newStructure.nextId);
+    return formatSuccessDirect({
+        bufferId: args.bufferId,
+        success: true,
+        operationsCompleted: operations.length,
+        oldSize,
+        newSize: newContent.length,
+        structure: newStructure.structure,
+        nextId: newStructure.nextId,
+        ...(allInsertedIds.length > 0 && { insertedIds: allInsertedIds }),
+        ...(diagramTypes.length > 0 && { diagramTypes }),
+    }, { truncateHint: "Structure preview truncated. Use buffer_get_structure for full view." });
 }
 /**
- * Check if content type indicates binary data that needs base64 decoding
+ * Handle plain text/JSON buffer editing with string replacement or append.
  */
-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));
+function handlePlainTextEdit(args) {
+    // Handle append for plain/json buffers
+    if (args.append && args.content) {
+        const result = contentBuffer.append(args.bufferId, args.content);
+        if (!result) {
+            return formatError({
+                error: true,
+                message: `Buffer not found or expired: ${args.bufferId}`,
+                statusCode: 404,
+            });
+        }
+        return formatSuccess({
+            bufferId: args.bufferId,
+            success: true,
+            operation: "append",
+            oldSize: result.oldSize,
+            newSize: result.newSize,
+        });
+    }
+    // String replacement requires old_string and new_string
+    if (args.old_string === undefined || args.new_string === undefined) {
+        return formatError({
+            error: true,
+            message: "For plain/json buffers: use old_string+new_string for replacement, or append=true+content for appending",
+            statusCode: 400,
+            details: {
+                hint: "To append content, use: buffer_edit(bufferId, append=true, content='text to add')",
+            },
+        });
+    }
+    const result = contentBuffer.edit(args.bufferId, args.old_string, args.new_string, args.replace_all ?? false);
+    if (!result) {
+        return formatError({
+            error: true,
+            message: `Buffer not found or expired: ${args.bufferId}`,
+            statusCode: 404,
+        });
+    }
+    if ("error" in result && result.error) {
+        return formatError({
+            error: true,
+            message: result.message,
+            statusCode: 400,
+            details: { occurrences: result.occurrences },
+        });
+    }
+    return formatSuccess(result);
 }
 export function createBufferTools() {
     return {
         buffer_create: {
-            description: `Create a new buffer with initial content. Returns bufferId and structure (for XHTML).
+            description: `Create a new buffer with initial content. Returns bufferId and structure.
 
-TIP: Call help(topic="storage") for XHTML syntax. Call help(topic="plantuml") for diagram syntax.
-
-For XHTML content, returns structure with element IDs for use with buffer_edit:
-- Each element gets a unique ID (stable during session)
-- Use buffer_edit with after/before/replace to modify by element ID`,
+Types: xhtml (Confluence storage, returns element IDs), json (data, use buffer_pipeline), plain (text).
+JSON accepts string or native object/array (auto-stringified).
+Run help(topic="storage") for XHTML syntax.`,
             inputSchema: z.object({
-                content: z.string().describe("Initial content for the buffer"),
+                content: z.union([
+                    z.string(),
+                    z.array(z.unknown()),
+                    z.record(z.unknown()),
+                ]).describe("Content: string for all types, or object/array for json (auto-stringified)"),
                 contentType: z.enum(["xhtml", "plain", "json"]).describe("Content type: 'xhtml' for Confluence, 'plain' for text, 'json' for data"),
                 metadata: z
                     .record(z.unknown())
@@ -105,6 +450,22 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
             }),
             handler: async (args) => {
                 try {
+                    // Auto-stringify objects/arrays for JSON content type
+                    let contentStr;
+                    if (typeof args.content === "string") {
+                        contentStr = args.content;
+                    }
+                    else if (args.contentType === "json") {
+                        // Auto-stringify native objects/arrays
+                        contentStr = JSON.stringify(args.content, null, 2);
+                    }
+                    else {
+                        return formatError({
+                            error: true,
+                            message: `Content must be a string for contentType '${args.contentType}'. Objects/arrays are only auto-stringified for contentType 'json'.`,
+                            statusCode: 400,
+                        });
+                    }
                     const mergedMetadata = {
                         ...args.metadata,
                         contentType: args.contentType,
@@ -112,9 +473,10 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
                     let bufferId;
                     let structure;
                     let nextId;
+                    let jsonStructure;
                     if (args.contentType === "xhtml") {
                         // Check for common CDATA mistake: wrapping entire content in CDATA
-                        const trimmedContent = args.content.trim();
+                        const trimmedContent = contentStr.trim();
                         if (trimmedContent.startsWith("<![CDATA[")) {
                             return formatError({
                                 error: true,
@@ -128,7 +490,7 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
                             });
                         }
                         // Parse XHTML and build structure with element IDs
-                        const parseResult = parseXhtml(args.content);
+                        const parseResult = parseXhtml(contentStr);
                         if (!parseResult.document) {
                             return formatError({
                                 error: true,
@@ -149,21 +511,67 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
                         const contentWithIds = serializeXhtml(parseResult.document);
                         bufferId = contentBuffer.storeWithStructure(contentWithIds, structure, nextId, mergedMetadata);
                     }
+                    else if (args.contentType === "json") {
+                        // Parse JSON and create structure with item IDs (for arrays)
+                        let data;
+                        try {
+                            data = JSON.parse(contentStr);
+                        }
+                        catch (e) {
+                            return formatError({
+                                error: true,
+                                message: `Invalid JSON: ${e.message}`,
+                                statusCode: 400,
+                            });
+                        }
+                        // Create JSON structure (handles arrays with IDs, objects with keys)
+                        const { content: contentWithIds, structure: jsonStruct } = createJsonStructure(data);
+                        jsonStructure = jsonStruct;
+                        bufferId = contentBuffer.storeJsonWithStructure(contentWithIds, jsonStruct, mergedMetadata);
+                    }
                     else {
-                        bufferId = contentBuffer.store(args.content, mergedMetadata);
+                        bufferId = contentBuffer.store(contentStr, mergedMetadata);
                     }
                     const info = contentBuffer.getInfo(bufferId);
+                    // Build response based on content type
+                    const isArray = jsonStructure?.rootType === "array";
+                    const isObject = jsonStructure?.rootType === "object";
+                    const preview = isArray
+                        ? jsonStructure?.items?.slice(0, 5).map(item => ({
+                            id: item.id,
+                            preview: item.preview,
+                        }))
+                        : undefined;
+                    // Build hint for JSON arrays
+                    const hint = args.contentType === "json" && isArray
+                        ? `Use buffer_pipeline(sourceBufferId='${bufferId}', pipeline={...}) to filter, transform, and output as XHTML/CSV/JSON.`
+                        : args.contentType === "json"
+                            ? `Use buffer_get_chunk to read raw content, or buffer_grep to search.`
+                            : undefined;
                     return formatSuccess({
                         bufferId,
-                        totalSize: info?.totalSize ?? args.content.length,
+                        bufferSizeBytes: info?.bufferSizeBytes ?? contentStr.length,
                         contentType: args.contentType,
                         createdAt: info ? new Date(info.createdAt).toISOString() : new Date().toISOString(),
                         expiresAt: info ? new Date(info.expiresAt).toISOString() : undefined,
                         metadata: mergedMetadata,
+                        // XHTML structure
                         ...(structure && { structure, nextId }),
+                        // JSON structure
+                        ...(jsonStructure && {
+                            structure: {
+                                type: jsonStructure.rootType,
+                                ...(isArray && { itemCount: jsonStructure.itemCount }),
+                                ...(isArray && preview && { preview }),
+                                ...(isObject && { keys: jsonStructure.keys }),
+                            },
+                        }),
+                        ...(hint && { hint }),
                         message: args.contentType === "xhtml"
                             ? "Buffer created with element IDs. Use buffer_edit with after/before/replace to modify."
-                            : "Buffer created.",
+                            : args.contentType === "json"
+                                ? "JSON buffer created. Use buffer_pipeline for transformation."
+                                : "Buffer created.",
                     });
                 }
                 catch (error) {
@@ -172,7 +580,13 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
             },
         },
         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.`,
+            description: `Retrieve a chunk of buffered content by buffer ID. Returns raw character-based content chunks.
+
+WARNING: NOT available for JSON arrays or XHTML content. Use instead:
+- JSON arrays: buffer_get_items(bufferId, start, count) - returns complete items
+- XHTML: buffer_get_element(bufferId, elementId) - returns element content
+
+Use buffer_get_chunk only for: plain text buffers or raw character access.`,
             inputSchema: z.object({
                 bufferId: z.string().describe("Buffer ID from previous tool response"),
                 offset: z
@@ -183,12 +597,49 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
                 limit: z
                     .number()
                     .optional()
-                    .default(5000)
-                    .describe("Maximum characters to return (default: 5000)"),
+                    .default(DEFAULT_CHUNK_SIZE)
+                    .describe(`Maximum characters to return (default: ${DEFAULT_CHUNK_SIZE})`),
             }),
             handler: async (args) => {
                 try {
-                    const chunk = contentBuffer.getChunk(args.bufferId, args.offset ?? 0, args.limit ?? 5000);
+                    // Check buffer info to block structured content types
+                    const bufferInfo = contentBuffer.getInfo(args.bufferId);
+                    if (!bufferInfo) {
+                        return formatError({
+                            error: true,
+                            message: `Buffer not found or expired: ${args.bufferId}`,
+                            statusCode: 404,
+                        });
+                    }
+                    const contentType = bufferInfo.metadata?.contentType;
+                    // Block JSON arrays - force use of buffer_get_items
+                    if (contentType === "json" && bufferInfo.jsonStructure?.rootType === "array") {
+                        return formatError({
+                            error: true,
+                            message: "buffer_get_chunk is not available for JSON array buffers. Use buffer_get_items instead for complete, non-truncated items.",
+                            statusCode: 400,
+                            details: {
+                                bufferId: args.bufferId,
+                                correctTool: "buffer_get_items",
+                                example: `buffer_get_items(bufferId="${args.bufferId}", start=0, count=50)`,
+                            },
+                        });
+                    }
+                    // Block XHTML - force use of buffer_get_element
+                    if (contentType === "xhtml") {
+                        return formatError({
+                            error: true,
+                            message: "buffer_get_chunk is not available for XHTML buffers. Use buffer_get_element for element-based access.",
+                            statusCode: 400,
+                            details: {
+                                bufferId: args.bufferId,
+                                correctTool: "buffer_get_element",
+                                example: `buffer_get_element(bufferId="${args.bufferId}", elementId=N)`,
+                                tip: "Use the 'structure' field in the buffer response to find element IDs",
+                            },
+                        });
+                    }
+                    const chunk = contentBuffer.getChunk(args.bufferId, args.offset ?? 0, args.limit ?? DEFAULT_CHUNK_SIZE);
                     if (!chunk) {
                         return formatError({
                             error: true,
@@ -196,34 +647,117 @@ For XHTML content, returns structure with element IDs for use with buffer_edit:
                             statusCode: 404,
                         });
                     }
-                    return formatSuccess({
+                    return formatSuccessDirect({
                         bufferId: chunk.bufferId,
                         content: chunk.chunk,
                         offset: chunk.offset,
                         limit: chunk.limit,
-                        totalSize: chunk.totalSize,
+                        bufferSizeBytes: chunk.bufferSizeBytes,
                         hasMore: chunk.hasMore,
                         metadata: chunk.metadata,
-                    });
+                    }, { truncateHint: `Use smaller limit (current: ${args.limit ?? DEFAULT_CHUNK_SIZE}).` });
                 }
                 catch (error) {
                     return formatError(error instanceof Error ? error : new Error(String(error)));
                 }
             },
         },
-        buffer_list: {
-            description: `List all active buffers with metadata. Buffers expire after 1 hour.
+        buffer_get_items: {
+            description: `Retrieve complete JSON array items from a buffer. Use for JSON buffers from jira_search_issues, etc.
 
-Use to recover lost buffer IDs or find buffers associated with Confluence drafts.
+Unlike buffer_get_chunk (which returns truncated raw text), this returns complete parsed items.
 
-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:
+  jira_search_issues(jql="project = PROJ") → bufferId with 500 issues
+  buffer_get_items(bufferId, start=0, count=10) → first 10 complete issue objects
 
-Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345"`,
+Returns: items (array), totalItems, hasMore, start, count`,
+            inputSchema: z.object({
+                bufferId: z.string().describe("Buffer ID containing JSON array"),
+                start: z
+                    .number()
+                    .optional()
+                    .default(0)
+                    .describe("Index to start from (default: 0)"),
+                count: z
+                    .number()
+                    .optional()
+                    .default(DEFAULT_BATCH_COUNT)
+                    .describe(`Number of items to return (default: ${DEFAULT_BATCH_COUNT}, max: ${MAX_BATCH_ITEMS})`),
+            }),
+            handler: async (args) => {
+                try {
+                    // Type-safe buffer access: buffer_get_items requires JSON buffer
+                    const typeError = validateBufferType(args.bufferId, ["json"], "buffer_get_items");
+                    if (typeError)
+                        return typeError.result;
+                    // Get full 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.bufferSizeBytes);
+                    if (!chunk) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to read buffer: ${args.bufferId}`,
+                            statusCode: 500,
+                        });
+                    }
+                    // Parse JSON array
+                    let data;
+                    try {
+                        const parsed = JSON.parse(chunk.chunk);
+                        if (!Array.isArray(parsed)) {
+                            return formatError({
+                                error: true,
+                                message: "Buffer content is not a JSON array",
+                                statusCode: 400,
+                                details: { type: typeof parsed },
+                            });
+                        }
+                        data = parsed;
+                    }
+                    catch (e) {
+                        return formatError({
+                            error: true,
+                            message: `Failed to parse JSON: ${e.message}`,
+                            statusCode: 400,
+                        });
+                    }
+                    // Slice items
+                    const start = args.start ?? 0;
+                    const count = Math.min(args.count ?? DEFAULT_BATCH_COUNT, MAX_BATCH_ITEMS);
+                    const items = data.slice(start, start + count);
+                    const hasMore = start + count < data.length;
+                    // Get schema from first item for reference
+                    let itemSchema;
+                    if (data.length > 0 && typeof data[0] === "object" && data[0] !== null) {
+                        itemSchema = Object.keys(data[0]);
+                    }
+                    return formatSuccess({
+                        bufferId: args.bufferId,
+                        items,
+                        totalItems: data.length,
+                        start,
+                        count: items.length,
+                        hasMore,
+                        nextStart: hasMore ? start + count : undefined,
+                        itemSchema: itemSchema ? itemSchema.slice(0, 20) : undefined, // First 20 keys
+                    });
+                }
+                catch (error) {
+                    return formatError(error instanceof Error ? error : new Error(String(error)));
+                }
+            },
+        },
+        buffer_list: {
+            description: `List all active buffers with metadata. Buffers expire after 1 hour (24h if modified).
+Max 20 buffers; oldest unmodified evicted first when full. Use to recover lost buffer IDs.`,
             inputSchema: z.object({}),
             handler: async () => {
                 try {
@@ -379,16 +913,11 @@ Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345
                                         type: "text",
                                         text: JSON.stringify({
                                             _pagination: true,
-                                            status: "SUCCESS - Search results buffered",
                                             bufferId: newBufferId,
-                                            totalSize: fullText.length,
                                             totalMatches: grepResult.totalMatches,
                                             hasMore: true,
-                                            next_action: {
-                                                tool: "buffer_get_chunk",
-                                                args: { bufferId: newBufferId, offset: 0, limit: 5000 },
-                                            },
-                                        }, null, 2),
+                                            next: { tool: "buffer_get_chunk", args: { bufferId: newBufferId, offset: 0, limit: DEFAULT_CHUNK_SIZE } },
+                                        }),
                                     },
                                 ],
                             };
@@ -403,8 +932,8 @@ Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345
                             ],
                         };
                     }
-                    // JSON mode - use formatSuccess which handles buffering automatically
-                    return formatSuccess(grepResult);
+                    // JSON mode - use formatSuccessDirect to avoid re-buffering
+                    return formatSuccessDirect(grepResult, { truncateHint: "Many matches. Use more specific pattern or add head_limit parameter." });
                 }
                 catch (error) {
                     return formatError(error instanceof Error ? error : new Error(String(error)));
@@ -412,39 +941,13 @@ Example: Find buffer for draft 12345 → look for metadata.resourceId === "12345
             },
         },
         buffer_edit: {
-            description: `Edit buffer content. For XHTML buffers, use element IDs. For plain/json, use string replacement.
-
-TIP: Call help(topic="plantuml") BEFORE using plantuml parameter. Call help(topic="storage") for XHTML syntax.
-
-XHTML editing (by element ID) - single operation:
-- after: Insert content after element with this ID
-- before: Insert content before element with this ID
-- replace: Replace element with this ID
-- append: Add content at document end
-- remove: Remove element with this ID
-- content: XHTML to insert/replace (PlantUML macros FORBIDDEN - use plantuml parameter)
-- plantuml: PlantUML code (auto-wrapped in Confluence macro, validated via Docker)
-- fromBufferId: Insert content from another buffer (useful for composing content)
-
-XHTML batch editing - multiple operations in one call:
-- operations: Array of {after?, before?, replace?, append?, remove?, content?, plantuml?, fromBufferId?}
-- Operations are executed sequentially; stops on first error
-- Much more efficient than multiple tool calls (parse once, serialize once)
-
-Example batch: operations=[{after:6, plantuml:"@startuml..."}, {after:8, fromBufferId:"buf_xxx"}]
-
-EDITING EXISTING PAGES with separate buffer:
-1. confluence_edit(URL) → bufferId_A (page content with structure)
-2. buffer_create(content) → bufferId_B (your new content)
-3. buffer_edit(bufferId=bufferId_A, after=X, fromBufferId=bufferId_B) → inserts B into A
-4. confluence_draft_create(pageId, bufferId_A) → creates draft with combined content
+            description: `Edit buffer content by element ID (XHTML) or string match (plain/JSON).
 
-Plain/JSON editing (string replacement):
-- old_string: Text to replace
-- new_string: Replacement text
-- replace_all: Replace all occurrences
+XHTML: after/before/replace/remove by element ID. content="<p>...</p>" | plantuml="@startuml..." | fromBufferId="buf_xxx"
+BATCH: operations=[{after:6,content:"<p>A</p>"},{remove:8}] — one call instead of many.
+Plain/JSON: old_string + new_string, or append=true + content.
 
-Returns updated structure for XHTML buffers.`,
+Run help(topic="buffers") for editing guide and examples.`,
             inputSchema: z.object({
                 bufferId: z.string().describe("Buffer ID to modify"),
                 // XHTML batch operations
@@ -483,293 +986,11 @@ Returns updated structure for XHTML buffers.`,
                         });
                     }
                     const isXhtml = bufferInfo.metadata?.contentType === "xhtml";
-                    // XHTML editing with element IDs
+                    // Dispatch to content-type-specific handler
                     if (isXhtml) {
-                        let operations;
-                        if (args.operations && args.operations.length > 0) {
-                            // Batch mode: use operations array
-                            operations = args.operations;
-                        }
-                        else {
-                            // Single operation mode (backwards compatible)
-                            const hasIdOperation = args.after !== undefined || args.before !== undefined ||
-                                args.replace !== undefined || args.append || args.remove !== undefined;
-                            if (!hasIdOperation) {
-                                return formatError({
-                                    error: true,
-                                    message: "XHTML buffer requires element ID operation: after, before, replace, append, remove, or operations array",
-                                    statusCode: 400,
-                                    details: {
-                                        structure: bufferInfo.structure,
-                                        nextId: bufferInfo.nextId,
-                                        hint: "Use after=ID, before=ID, replace=ID, append=true, remove=ID, or operations=[...]",
-                                    },
-                                });
-                            }
-                            operations = [{
-                                    after: args.after,
-                                    before: args.before,
-                                    replace: args.replace,
-                                    append: args.append,
-                                    remove: args.remove,
-                                    content: args.content,
-                                    plantuml: args.plantuml,
-                                    fromBufferId: args.fromBufferId,
-                                }];
-                        }
-                        // PHASE 0: Resolve fromBufferId to content for all operations
-                        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
-                            const op = operations[opIndex];
-                            if (op.fromBufferId) {
-                                // Validate source buffer exists
-                                const sourceInfo = contentBuffer.getInfo(op.fromBufferId);
-                                if (!sourceInfo) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: Source buffer '${op.fromBufferId}' not found or expired`,
-                                        statusCode: 404,
-                                    });
-                                }
-                                // Get source buffer content
-                                const sourceChunk = contentBuffer.getChunk(op.fromBufferId, 0, sourceInfo.totalSize);
-                                if (!sourceChunk) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: Failed to read source buffer '${op.fromBufferId}'`,
-                                        statusCode: 500,
-                                    });
-                                }
-                                // Merge content: fromBufferId content takes precedence, but can be combined with plantuml
-                                if (!op.content) {
-                                    op.content = sourceChunk.chunk;
-                                }
-                                else {
-                                    // If both content and fromBufferId, concatenate
-                                    op.content = op.content + sourceChunk.chunk;
-                                }
-                                // Clear fromBufferId since we've resolved it
-                                delete op.fromBufferId;
-                            }
-                        }
-                        // Get buffer content
-                        const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
-                        if (!chunk) {
-                            return formatError({
-                                error: true,
-                                message: `Failed to read buffer: ${args.bufferId}`,
-                                statusCode: 500,
-                            });
-                        }
-                        // Parse XHTML once
-                        const parseResult = parseXhtml(chunk.chunk);
-                        if (!parseResult.document) {
-                            return formatError({
-                                error: true,
-                                message: `Failed to parse XHTML: ${parseResult.error?.message}`,
-                                statusCode: 400,
-                            });
-                        }
-                        const oldSize = chunk.chunk.length;
-                        let nextId = bufferInfo.nextId ?? 1;
-                        const allInsertedIds = [];
-                        const diagramTypes = [];
-                        // PHASE 1: Check for PlantUML macros in content parameters (FORBIDDEN)
-                        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
-                            const op = operations[opIndex];
-                            if (op.content) {
-                                const plantUmlDetection = detectPlantUmlInContent(op.content);
-                                if (plantUmlDetection) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: PlantUML macros in 'content' parameter are forbidden. Use 'plantuml' parameter for validated insertion.`,
-                                        statusCode: 400,
-                                        details: {
-                                            operationIndex: opIndex,
-                                            macrosFound: plantUmlDetection.count,
-                                            hint: plantUmlDetection.hint,
-                                        },
-                                    });
-                                }
-                            }
-                        }
-                        // PHASE 2: Pre-validate ALL PlantUML before any DOM mutations
-                        const validatedPlantUml = new Map();
-                        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
-                            const op = operations[opIndex];
-                            if (op.plantuml) {
-                                const validation = await validatePlantUmlWithFallback(op.plantuml, "insert-plantuml", {});
-                                if (!validation.valid) {
-                                    // Type-safe error extraction
-                                    let errorData = {
-                                        error: true,
-                                        message: "PlantUML validation failed",
-                                        operationIndex: opIndex,
-                                        completedOperations: 0,
-                                        phase: "pre-validation",
-                                    };
-                                    // Safely extract error details if available
-                                    const errorObj = validation.error;
-                                    if (errorObj &&
-                                        "content" in errorObj &&
-                                        Array.isArray(errorObj.content) &&
-                                        errorObj.content[0]?.text) {
-                                        try {
-                                            const parsed = JSON.parse(errorObj.content[0].text);
-                                            errorData = {
-                                                ...parsed,
-                                                operationIndex: opIndex,
-                                                completedOperations: 0,
-                                                phase: "pre-validation",
-                                            };
-                                        }
-                                        catch {
-                                            // Keep default errorData if parsing fails
-                                        }
-                                    }
-                                    return {
-                                        content: [{ type: "text", text: JSON.stringify(errorData, null, 2) }],
-                                    };
-                                }
-                                validatedPlantUml.set(opIndex, validation);
-                            }
-                        }
-                        // PHASE 3: Execute operations (all PlantUML pre-validated)
-                        // Note: Rollback is implicit - buffer is only updated after ALL operations succeed
-                        for (let opIndex = 0; opIndex < operations.length; opIndex++) {
-                            const op = operations[opIndex];
-                            // Build content to insert (use pre-validated PlantUML)
-                            let contentToInsert = op.content;
-                            let diagramType;
-                            if (op.plantuml) {
-                                // Use pre-validated PlantUML (already validated in PHASE 2)
-                                const validation = validatedPlantUml.get(opIndex);
-                                contentToInsert = buildPlantUmlMacro(validation);
-                                diagramType = validation.diagramType;
-                                if (diagramType)
-                                    diagramTypes.push(diagramType);
-                            }
-                            // Execute single operation
-                            let result;
-                            if (op.remove !== undefined) {
-                                result = removeById(parseResult.document, op.remove);
-                            }
-                            else if (op.replace !== undefined) {
-                                if (!contentToInsert) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: content or plantuml required for replace operation`,
-                                        statusCode: 400,
-                                    });
-                                }
-                                result = replaceById(parseResult.document, op.replace, contentToInsert);
-                            }
-                            else if (op.append) {
-                                if (!contentToInsert) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: content or plantuml required for append operation`,
-                                        statusCode: 400,
-                                    });
-                                }
-                                result = appendToDocument(parseResult.document, contentToInsert, nextId);
-                                if (result.nextId)
-                                    nextId = result.nextId;
-                            }
-                            else if (op.after !== undefined) {
-                                if (!contentToInsert) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: content or plantuml required for after operation`,
-                                        statusCode: 400,
-                                    });
-                                }
-                                result = insertById(parseResult.document, op.after, "after", contentToInsert, nextId);
-                                if (result.nextId)
-                                    nextId = result.nextId;
-                            }
-                            else if (op.before !== undefined) {
-                                if (!contentToInsert) {
-                                    return formatError({
-                                        error: true,
-                                        message: `Operation ${opIndex + 1}: content or plantuml required for before operation`,
-                                        statusCode: 400,
-                                    });
-                                }
-                                result = insertById(parseResult.document, op.before, "before", contentToInsert, nextId);
-                                if (result.nextId)
-                                    nextId = result.nextId;
-                            }
-                            else {
-                                return formatError({
-                                    error: true,
-                                    message: `Operation ${opIndex + 1}: No valid operation specified (need after, before, replace, append, or remove)`,
-                                    statusCode: 400,
-                                });
-                            }
-                            if (!result.success) {
-                                // Operation failed - buffer NOT updated (atomic rollback)
-                                return formatError({
-                                    error: true,
-                                    message: `Operation ${opIndex + 1} failed: ${result.error || "Unknown error"}. Buffer unchanged (atomic rollback).`,
-                                    statusCode: 400,
-                                    details: {
-                                        operationIndex: opIndex,
-                                        completedOperations: 0, // No operations persisted due to rollback
-                                        operation: op,
-                                        structure: bufferInfo.structure,
-                                        nextId: bufferInfo.nextId,
-                                        rollback: true,
-                                    },
-                                });
-                            }
-                            // Collect inserted IDs
-                            if (result.insertedIds) {
-                                allInsertedIds.push(...result.insertedIds);
-                            }
-                        }
-                        // Serialize and update buffer once (after all operations)
-                        const newContent = serializeXhtml(parseResult.document);
-                        // Rebuild structure
-                        const newStructure = parseStructure(parseResult.document);
-                        // Update buffer
-                        contentBuffer.update(args.bufferId, newContent, { contentType: "xhtml" }, newStructure.structure, newStructure.nextId);
-                        return formatSuccess({
-                            bufferId: args.bufferId,
-                            success: true,
-                            operationsCompleted: operations.length,
-                            oldSize,
-                            newSize: newContent.length,
-                            structure: newStructure.structure,
-                            nextId: newStructure.nextId,
-                            ...(allInsertedIds.length > 0 && { insertedIds: allInsertedIds }),
-                            ...(diagramTypes.length > 0 && { diagramTypes }),
-                        });
+                        return handleXhtmlEdit(args, bufferInfo);
                     }
-                    // Plain text/JSON editing
-                    if (args.old_string === undefined || args.new_string === undefined) {
-                        return formatError({
-                            error: true,
-                            message: "old_string and new_string required for plain/json buffer editing",
-                            statusCode: 400,
-                        });
-                    }
-                    const result = contentBuffer.edit(args.bufferId, args.old_string, args.new_string, args.replace_all ?? false);
-                    if (!result) {
-                        return formatError({
-                            error: true,
-                            message: `Buffer not found or expired: ${args.bufferId}`,
-                            statusCode: 404,
-                        });
-                    }
-                    if ("error" in result && result.error) {
-                        return formatError({
-                            error: true,
-                            message: result.message,
-                            statusCode: 400,
-                            details: { occurrences: result.occurrences },
-                        });
-                    }
-                    return formatSuccess(result);
+                    return handlePlainTextEdit(args);
                 }
                 catch (error) {
                     return formatError(error instanceof Error ? error : new Error(String(error)));
@@ -789,29 +1010,15 @@ Each element has:
             }),
             handler: async (args) => {
                 try {
+                    // Type-safe buffer access: buffer_get_structure requires XHTML buffer
+                    const typeError = validateBufferType(args.bufferId, ["xhtml"], "buffer_get_structure");
+                    if (typeError)
+                        return typeError.result;
                     const bufferInfo = contentBuffer.getInfo(args.bufferId);
-                    if (!bufferInfo) {
-                        return formatError({
-                            error: true,
-                            message: `Buffer not found or expired: ${args.bufferId}`,
-                            statusCode: 404,
-                        });
-                    }
-                    if (bufferInfo.metadata?.contentType !== "xhtml") {
-                        return formatError({
-                            error: true,
-                            message: "Buffer is not XHTML content",
-                            statusCode: 400,
-                            details: {
-                                contentType: bufferInfo.metadata?.contentType,
-                                hint: "Structure is only available for XHTML buffers",
-                            },
-                        });
-                    }
                     return formatSuccess({
                         bufferId: args.bufferId,
-                        structure: bufferInfo.structure ?? [],
-                        nextId: bufferInfo.nextId ?? 1,
+                        structure: bufferInfo?.structure ?? [],
+                        nextId: bufferInfo?.nextId ?? 1,
                     });
                 }
                 catch (error) {
@@ -833,6 +1040,10 @@ Example: After a Confluence error at element 12, use this to see the content:
             }),
             handler: async (args) => {
                 try {
+                    // Type-safe buffer access: buffer_get_element requires XHTML buffer
+                    const typeError = validateBufferType(args.bufferId, ["xhtml"], "buffer_get_element");
+                    if (typeError)
+                        return typeError.result;
                     const bufferInfo = contentBuffer.getInfo(args.bufferId);
                     if (!bufferInfo) {
                         return formatError({
@@ -841,15 +1052,8 @@ Example: After a Confluence error at element 12, use this to see the content:
                             statusCode: 404,
                         });
                     }
-                    if (bufferInfo.metadata?.contentType !== "xhtml") {
-                        return formatError({
-                            error: true,
-                            message: "Buffer is not XHTML content",
-                            statusCode: 400,
-                        });
-                    }
                     // Get full buffer content
-                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.bufferSizeBytes);
                     if (!chunk) {
                         return formatError({
                             error: true,
@@ -906,20 +1110,8 @@ Example: After a Confluence error at element 12, use this to see the content:
             },
         },
         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.`,
+            description: `Validate buffered XHTML as Confluence storage format. Checks well-formedness, required attributes, macro names, and PlantUML syntax (if Docker running).
+Use before confluence_draft_create to catch errors early.`,
             inputSchema: z.object({
                 bufferId: z.string().describe("Buffer ID containing XHTML content"),
                 validatePlantUml: z
@@ -930,6 +1122,10 @@ Use this to validate content before calling confluence_update_page or confluence
             }),
             handler: async (args) => {
                 try {
+                    // Type-safe buffer access: buffer_validate_xhtml requires XHTML buffer
+                    const typeError = validateBufferType(args.bufferId, ["xhtml"], "buffer_validate_xhtml");
+                    if (typeError)
+                        return typeError.result;
                     // Get buffer content
                     const bufferInfo = contentBuffer.getInfo(args.bufferId);
                     if (!bufferInfo) {
@@ -939,7 +1135,7 @@ Use this to validate content before calling confluence_update_page or confluence
                             statusCode: 404,
                         });
                     }
-                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.totalSize);
+                    const chunk = contentBuffer.getChunk(args.bufferId, 0, bufferInfo.bufferSizeBytes);
                     if (!chunk) {
                         return formatError({
                             error: true,
@@ -988,91 +1184,142 @@ Use this to validate content before calling confluence_update_page or confluence
                 }
             },
         },
-        buffer_save_to_file: {
-            description: `Save buffer content to a file within the project directory.
+        // =========================================================================
+        // Buffer Pipeline - Unified data transformation tool
+        // =========================================================================
+        buffer_pipeline: {
+            description: `Transform JSON array with declarative pipeline (server-side, 98% token reduction).
 
-SECURITY: Files can only be saved within the project root (directory containing .jicon.json).
-Attempts to write outside this directory will be rejected.
+STAGES: select → filter → groupBy → sort → limit → format → output (required)
+OUTPUT: xhtml_table | xhtml_list | json | csv | markdown
+NOTE: xhtml/csv/md outputs are NOT iterable (buffer_get_items won't work). json IS iterable.
+RETURNS: bufferId, contentType, itemCount
 
-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: pipeline={filter:[{field:"status.name",operator:"ne",value:"Done"}],output:{type:"xhtml_table",table:{columns:[{field:"key"},{field:"summary"}]}}}
 
-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)"),
-            }),
+IMPORTANT: pipeline must be object (not string). Use "sort" (not "sortBy"). output is REQUIRED.
+Run help(topic="buffers") for full schema, operators, and examples.`,
+            inputSchema: BufferPipelineInputSchema,
             handler: async (args) => {
                 try {
-                    // 1. Validate buffer exists
-                    const info = contentBuffer.getInfo(args.bufferId);
-                    if (!info) {
+                    // Type-safe buffer access: buffer_pipeline requires JSON buffer
+                    const typeError = validateBufferType(args.sourceBufferId, ["json"], "buffer_pipeline");
+                    if (typeError)
+                        return typeError.result;
+                    // 1. Get buffer info
+                    const bufferInfo = contentBuffer.getInfo(args.sourceBufferId);
+                    if (!bufferInfo) {
                         return formatError({
                             error: true,
-                            message: `Buffer not found: ${args.bufferId}`,
+                            message: `Buffer not found or expired: ${args.sourceBufferId}`,
                             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) {
+                    // 2. Get buffer content
+                    const chunk = contentBuffer.getChunk(args.sourceBufferId, 0, bufferInfo.bufferSizeBytes);
+                    if (!chunk) {
                         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')",
-                            },
+                            message: `Failed to read buffer content: ${args.sourceBufferId}`,
+                            statusCode: 500,
                         });
                     }
-                    // 4. Get buffer content
-                    const chunk = contentBuffer.getChunk(args.bufferId, 0, info.totalSize);
-                    if (!chunk) {
+                    // 3. Parse JSON array
+                    let data;
+                    try {
+                        const parsed = JSON.parse(chunk.chunk);
+                        if (!Array.isArray(parsed)) {
+                            return formatError({
+                                error: true,
+                                message: "Buffer content is not a JSON array. buffer_pipeline requires array data.",
+                                statusCode: 400,
+                                details: { type: typeof parsed },
+                            });
+                        }
+                        data = parsed;
+                    }
+                    catch (e) {
                         return formatError({
                             error: true,
-                            message: `Failed to read buffer: ${args.bufferId}`,
-                            statusCode: 500,
+                            message: `Failed to parse buffer as JSON: ${e.message}`,
+                            statusCode: 400,
                         });
                     }
-                    // 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}`,
+                    // 4. Build pipeline context
+                    const context = {
+                        sourceBufferId: args.sourceBufferId,
+                        jiraUrl: process.env.JIRA_URL,
+                        confluenceUrl: process.env.CONFLUENCE_URL,
+                        metadata: bufferInfo.metadata,
+                    };
+                    // 5. Dry run - validate only
+                    if (args.dryRun) {
+                        const validation = validatePipeline(data, args.pipeline);
+                        return formatSuccessDirect({
+                            dryRun: true,
+                            valid: validation.valid,
+                            errors: validation.errors,
+                            warnings: validation.warnings,
+                            availableFields: validation.availableFields,
+                            itemCount: data.length,
+                        });
+                    }
+                    // 6. Execute pipeline
+                    const pipelineResult = executePipelineWithOutput(data, args.pipeline, context);
+                    if ("error" in pipelineResult) {
+                        return formatError(pipelineResult.error);
+                    }
+                    // 7. Store output in buffer
+                    const { result, output } = pipelineResult;
+                    const outputType = args.pipeline.output.type;
+                    // Determine content type for buffer
+                    const contentType = outputType.startsWith("xhtml")
+                        ? "xhtml"
+                        : outputType === "json"
+                            ? "json"
+                            : "plain";
+                    const bufferMetadata = {
+                        contentType,
+                        resourceType: "pipeline_output",
+                        sourceBufferId: args.sourceBufferId,
+                        pipelineStages: result.pipelineStages,
+                        outputType,
+                    };
+                    let newBufferId;
+                    if (contentType === "xhtml") {
+                        // Parse XHTML to get structure with element IDs
+                        const parseResult = parseXhtml(output);
+                        if (parseResult.document) {
+                            const structureResult = parseStructure(parseResult.document);
+                            // Re-serialize to include data-jicon-id attributes
+                            const contentWithIds = serializeXhtml(parseResult.document);
+                            newBufferId = contentBuffer.storeWithStructure(contentWithIds, structureResult.structure, structureResult.nextId, bufferMetadata);
+                        }
+                        else {
+                            // Fallback: store without structure if parsing fails
+                            newBufferId = contentBuffer.store(output, bufferMetadata);
+                        }
+                    }
+                    else if (contentType === "json") {
+                        // Parse JSON to get structure with item IDs
+                        try {
+                            const data = JSON.parse(output);
+                            const { content: contentWithIds, structure: jsonStruct } = createJsonStructure(data);
+                            newBufferId = contentBuffer.storeJsonWithStructure(contentWithIds, jsonStruct, bufferMetadata);
+                        }
+                        catch {
+                            // Fallback: store without structure if parsing fails
+                            newBufferId = contentBuffer.store(output, bufferMetadata);
+                        }
+                    }
+                    else {
+                        newBufferId = contentBuffer.store(output, bufferMetadata);
+                    }
+                    // 8. Return result with bufferId
+                    return formatSuccessDirect({
+                        ...result,
+                        bufferId: newBufferId,
+                        contentType,
                     });
                 }
                 catch (error) {