@crypto512/jicon-mcp 1.3.0 → 2.0.0

package/dist/utils/jicon-help.js

@@ -6,12 +6,13 @@
  */
 import { z } from "zod";
 import { formatSuccess, formatError } from "./response-formatter.js";
-import { ALLOWED_INCLUDE_URLS } from "./plantuml/index.js";
 // Available topics
 const TOPICS = ["jql", "cql", "storage", "plantuml", "buffers"];
 // Default workflow guide (shown when no topic specified)
 const WORKFLOW_GUIDE = `# Jicon Quick Reference
 
+TOOLS: jira(16) confluence(18) tempo(11) buffer(14) plantuml(3) url(2) help(1)
+
 ## Decision Tree - Which Topic?
 
 | Task | First Step |
@@ -23,6 +24,9 @@ const WORKFLOW_GUIDE = `# Jicon Quick Reference
 | Search Confluence | \`help(topic="cql")\` |
 | Search Jira | \`jira_get_issue_types()\` then \`help(topic="jql")\` |
 | Log/get time | \`tempo_get_user_info()\` first |
+| **Create table from Jira data** | \`buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table"}})\` |
+| **Iterate items for AI analysis** | \`buffer_get_items(bufferId, start=0, count=50)\` |
+| **Large dataset + AI columns** | Batch workflow - see \`help(topic="buffers")\` |
 
 ---
 
@@ -51,6 +55,11 @@ const WORKFLOW_GUIDE = `# Jicon Quick Reference
 - \`confluence_review_discard(reviewDraftId)\` - Discard without changes
 - \`confluence_review_list()\` - Find all review drafts for cleanup
 
+**Draft Management Tools:**
+- \`confluence_draft_list()\` - List all drafts in your personal space
+- \`confluence_draft_open(draftId)\` - Reopen a draft for editing
+- \`confluence_draft_delete(draftId)\` - Delete a draft
+
 ### Create NEW Confluence Page (Buffer-First)
 \`\`\`
 1. buffer_create(content="<h1>Title</h1><p>Content</p>", contentType="xhtml")
@@ -149,7 +158,17 @@ const JQL_HELP = `# JQL Syntax Guide
 - Relative dates: startOfDay(-7) = 7 days ago
 - Always quote field values that contain spaces
 - Issue type names may be localized (e.g., "Epopee" instead of "Epic")
-- Results are always buffered - use buffer_get_chunk to read, buffer_grep to search`;
+
+## Response Fields (jira_search_issues)
+- returnedItems: Items available in buffer (max 5000) - USE THIS
+- jiraTotalMatching: Total Jira found (may exceed returnedItems)
+- apiLimit: Maximum per search (5000)
+- If jiraTotalMatching > returnedItems, refine JQL to narrow results
+
+## Date Handling Tips
+- "Last week" in business context = previous Mon-Fri (e.g., Dec 8-12)
+- "Rolling 7 days" = use startOfDay(-7)
+- For exact date ranges, use explicit dates: updated >= "2025-12-08" AND updated <= "2025-12-12"`;
 // CQL syntax guide
 const CQL_HELP = `# CQL Syntax Guide
 
@@ -256,9 +275,37 @@ Confluence uses **XHTML** (strict XML), NOT loose HTML5. This matters!
 | Line break | \`<br/>\` (self-closing!) |
 | Horizontal rule | \`<hr/>\` (self-closing!) |
 | Code inline | \`<code>text</code>\` |
-| Link | \`<a href="url">text</a>\` |
 | List | \`<ul><li>item</li></ul>\` or \`<ol><li>...</li></ol>\` |
 
+## Links (IMPORTANT: Two Types!)
+
+### External Links (Jira, Web URLs)
+For links to external sites including Jira issues, use standard HTML anchor tags:
+\`\`\`xml
+<a href="https://jira.example.com/browse/PROJ-123">PROJ-123</a>
+<a href="https://example.com">Example Site</a>
+\`\`\`
+
+**Example: Jira links in a table:**
+\`\`\`xml
+<table><tbody>
+  <tr><th>Issue</th><th>Summary</th></tr>
+  <tr>
+    <td><a href="https://jira.example.com/browse/FR-1301">FR-1301</a></td>
+    <td>Fix login bug</td>
+  </tr>
+</tbody></table>
+\`\`\`
+
+### Confluence Page Links (Internal)
+For links to other Confluence pages, use the ac:link macro:
+\`\`\`xml
+<ac:link><ri:page ri:content-title="Page Title"/>
+  <ac:plain-text-link-body><![CDATA[Link Text]]></ac:plain-text-link-body>
+</ac:link>
+\`\`\`
+Cross-space: add \`ri:space-key="KEY"\` to ri:page
+
 ## Tables
 \`\`\`xml
 <table><tbody>
@@ -279,14 +326,6 @@ Merge cells: \`colspan="2"\`, \`rowspan="2"\`
 \`\`\`
 Types: \`single\`, \`two_equal\`, \`two_left_sidebar\`, \`two_right_sidebar\`, \`three_equal\`
 
-## Page Links
-\`\`\`xml
-<ac:link><ri:page ri:content-title="Page Title"/>
-  <ac:plain-text-link-body><![CDATA[Link Text]]></ac:plain-text-link-body>
-</ac:link>
-\`\`\`
-Cross-space: add \`ri:space-key="KEY"\` to ri:page
-
 ## Images
 \`\`\`xml
 <ac:image ac:width="300"><ri:attachment ri:filename="image.png"/></ac:image>
@@ -387,27 +426,28 @@ const PLANTUML_HELP = `# PlantUML in Confluence
 
 ## Stdlib Includes (C4, AWS, Azure)
 
-C4-PlantUML, AWS icons, and Azure diagrams are supported via \`!include\`:
+C4-PlantUML, AWS icons, Azure, and Kubernetes diagrams use PlantUML's built-in standard library.
+GitHub URLs are automatically converted to stdlib syntax:
+
+| GitHub URL | Converted to |
+|------------|--------------|
+| \`https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/.../C4_Context.puml\` | \`!include <C4/C4_Context>\` |
+| \`https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/.../dist/AWSCommon.puml\` | \`!include <awslib/AWSCommon>\` |
+| \`https://raw.githubusercontent.com/plantuml-stdlib/Azure-PlantUML/.../AzureCommon.puml\` | \`!include <azure/AzureCommon>\` |
+| \`https://raw.githubusercontent.com/plantuml-stdlib/plantuml-kubernetes-sprites/...\` | \`!include <kubernetes/...>\` |
 
+**Example (either syntax works):**
 \`\`\`
 @startuml
-!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include <C4/C4_Context>
 Person(user, "User")
 System(sys, "My System")
 Rel(user, sys, "Uses")
 @enduml
 \`\`\`
 
-**Requires \`plantumlInclude: true\`** (enabled by default in .jicon.json)
-
-When enabled, \`!include\` from whitelisted URLs are authorized and expanded client-side
-before validation and Confluence upload. Expanded includes are automatically collapsed
-back to \`!include\` directives when reading pages.
-
-**Whitelisted URL prefixes:**
-${ALLOWED_INCLUDE_URLS.map((url) => `- \`${url}\``).join("\n")}
-
-Non-whitelisted URLs are left unchanged (PlantUML server may reject them due to SSRF restrictions).
+GitHub URLs in diagrams are converted to stdlib syntax before validation and rendering.
+Non-convertible URLs are left unchanged and may fail if the PlantUML server can't fetch them.
 
 ## Quick Examples
 
@@ -431,7 +471,7 @@ User --> Order
 **C4 Context Diagram:**
 \`\`\`
 @startuml
-!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
+!include <C4/C4_Context>
 Person(user, "Customer", "Uses the system")
 System(sys, "E-Commerce", "Online store")
 System_Ext(pay, "Payment Gateway", "Processes payments")
@@ -576,9 +616,10 @@ When editing existing pages, you can create content in a separate buffer and mer
 
 | Tool | Use |
 |------|-----|
-| \`buffer_get_structure(bufferId)\` | View current element IDs |
+| \`buffer_get_structure(bufferId)\` | View current element IDs (XHTML) |
 | \`buffer_get_element(bufferId, elementId)\` | Get raw XHTML of specific element |
-| \`buffer_get_chunk(bufferId, offset, limit)\` | Read content in chunks |
+| \`buffer_get_items(bufferId, start, count)\` | Get complete JSON items (not truncated) |
+| \`buffer_get_chunk(bufferId, offset, limit)\` | Read raw content in character chunks |
 | \`buffer_grep(bufferId, pattern, "-C"=2)\` | Search with context |
 | \`buffer_validate_xhtml(bufferId)\` | Check XHTML validity |
 | \`buffer_list()\` | See all active buffers |
@@ -586,16 +627,200 @@ When editing existing pages, you can create content in a separate buffer and mer
 
 ## Plain/JSON Editing (non-XHTML)
 
+**String replacement:**
 \`\`\`
 buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 \`\`\`
 
+**Append content:**
+\`\`\`
+buffer_edit(bufferId, append=true, content="text to add at end")
+\`\`\`
+
+## JSON Pipeline (buffer_pipeline) - RECOMMENDED
+
+Transform JSON buffers with a declarative pipeline: filter, group, sort, format, output.
+
+**98% token reduction** for data transformations - no need to iterate through items!
+
+**Basic workflow:**
+\`\`\`
+1. jira_search_issues(jql="...") → { bufferId, structure: { itemCount: 578 } }
+
+2. buffer_pipeline(bufferId, pipeline={
+     filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+     sort: [{ field: "priority.name", direction: "asc" }],
+     output: {
+       type: "xhtml_table",
+       table: {
+         title: "Open Issues",
+         columns: [
+           { field: "key", header: "Issue", link: { type: "jira" } },
+           { field: "summary", header: "Summary" },
+           { field: "priority.name", header: "Priority" }
+         ]
+       }
+     }
+   })
+   → { bufferId: "buf_new", outputItems: 45, preview: "..." }
+
+3. Insert into Confluence page or use directly
+\`\`\`
+
+**Pipeline stages (all optional except output):**
+- \`select\`: Extract and rename fields
+- \`filter\`: Filter items (eq, ne, contains, in, regex, etc.)
+- \`groupBy\`: Group and aggregate (count, sum, avg, list, etc.)
+- \`sort\`: Sort by fields
+- \`limit\`: Limit results
+- \`format\`: Conditional styling (colors, bold, icons)
+- \`output\`: Generate output (xhtml_table, xhtml_list, json, csv, markdown)
+
+**Schema Quick Reference:**
+\`\`\`
+pipeline: {
+  select?: { fields: [{from: "path", as: "name", transform?: "..."}] },
+  filter?: [{ field, operator, value }],
+  groupBy?: { field, aggregations: [{function, field?, as}] },
+  sort?: [{ field, direction: "asc"|"desc" }],  // NOT "sortBy"!
+  limit?: number,
+  format?: [...],
+  output: { type: "xhtml_table"|"json"|"csv"|..., table?: {...} }
+}
+\`\`\`
+
+**Common Mistakes:**
+| Wrong | Correct |
+|-------|---------|
+| sortBy: [...] | sort: [...] |
+| transform: "map" | transform: "date" (or uppercase, lowercase, number, boolean, string) |
+| No output | output: {...} (REQUIRED) |
+| pipeline: "{...}" | pipeline: {...} (object, not string) |
+
+**After select renames fields, use NEW names in subsequent stages:**
+- select: {from: "issueType", as: "Type"}
+- sort: [{field: "Type"}] ✓ (not "issueType")
+
+**Filter operators:** eq, ne, gt, lt, gte, lte, contains, startsWith, endsWith, in, notIn, exists, notExists, regex, empty, notEmpty
+
+**Aggregations:** count, sum, avg, min, max, first, last, list, unique
+
+**Example - Statistics by assignee:**
+\`\`\`
+buffer_pipeline(bufferId, pipeline={
+  filter: [{ field: "status.name", operator: "ne", value: "Done" }],
+  groupBy: {
+    field: "assignee.displayName",
+    aggregations: [
+      { function: "count", as: "total" },
+      { function: "list", field: "key", as: "issues" }
+    ]
+  },
+  sort: [{ field: "total", direction: "desc" }],
+  output: {
+    type: "xhtml_table",
+    table: {
+      title: "Work Distribution",
+      columns: [
+        { field: "displayName", header: "Assignee" },
+        { field: "total", header: "Open Issues" },
+        { field: "issues", header: "Issue Keys" }
+      ]
+    }
+  }
+})
+\`\`\`
+
+**When to use buffer_pipeline:**
+- Generating tables/lists for Confluence
+- Creating CSV/Markdown exports
+- Aggregating statistics
+- Filtering and sorting large result sets server-side
+
+**When NOT to use buffer_pipeline:**
+- When you need LLM judgment on each item
+- When decisions require analyzing content (use buffer_get_items instead)
+
+## Decision Forks (Choose Your Path)
+
+After jira_search_issues/tempo_get_worklogs returns a bufferId, you have OPTIONS:
+
+| What You Need | Tool to Use | Result |
+|---------------|-------------|--------|
+| READ/ANALYZE items with AI | buffer_get_items(start=0, count=50) | Get items for analysis |
+| SEARCH within results | buffer_grep(pattern) | Find matching items |
+| FORMAT for Confluence | buffer_pipeline → xhtml_table | TERMINAL: publish-ready |
+| TRANSFORM and keep flexible | buffer_pipeline → json | Can process again |
+| EXPORT to file | buffer_pipeline → csv/markdown | TERMINAL: file-ready |
+
+**⚠️ OUTPUT TYPE CONSEQUENCES:**
+| Type | Can Iterate Items? | Can Edit? | Next Steps |
+|------|-------------------|-----------|------------|
+| json | ✓ buffer_get_items | ✓ buffer_pipeline | Further processing, re-transform |
+| xhtml_* | ✗ (not iterable) | ✓ buffer_edit | confluence_draft_create |
+| csv/md | ✗ (not iterable) | ✓ buffer_edit | buffer_get_chunk |
+
+**Choose json** if you need to iterate items for AI analysis (buffer_get_items).
+**Choose xhtml_*** when ready to publish - you can still edit elements, but can't iterate.
+
+---
+
+## Large Dataset Patterns
+
+### Simple table (no AI analysis)
+Use \`buffer_pipeline\` - generates complete table in **ONE tool call**:
+\`\`\`
+jira_search_issues(jql="...") → bufferId (500+ items)
+buffer_pipeline(bufferId, pipeline={output:{type:"xhtml_table",...}}) → complete table!
+\`\`\`
+
+### Table with AI-enhanced columns (complexity, impact)
+Use **batch accumulation workflow** - analyze items in batches, compose results:
+
+\`\`\`
+1. jira_search_issues(jql="...") → sourceBufferId (578 items)
+
+2. buffer_create(content="<table><thead>...</thead><tbody></tbody></table>", contentType="xhtml")
+   → accumulatorBufferId, structure (note tbody element ID)
+
+3. For each batch of 50 items:
+   buffer_get_items(sourceBufferId, start=X, count=50) → items[]
+   // AI analyzes items, builds XHTML rows with AI columns
+   buffer_create(content=rowsXHTML, contentType="xhtml") → batchBufferId
+   buffer_edit(accumulatorBufferId, after=lastRowId, fromBufferId=batchBufferId)
+
+4. buffer_edit(pageBufferId, after=ID, fromBufferId=accumulatorBufferId)
+   confluence_draft_create(pageId, pageBufferId) → draft for review
+\`\`\`
+
+---
+
+## Reading JSON Data (buffer_get_items, buffer_grep)
+
+For cases where you need to read and analyze the data (not just transform it):
+
+\`\`\`
+1. jira_search_issues(jql="...")
+   → { bufferId, structure: { itemCount: 519 } }
+
+2. buffer_get_items(bufferId, start=0, count=50)
+   → Get 50 complete items for analysis (not truncated)
+
+3. buffer_grep(bufferId, pattern="urgent")
+   → Search within buffer
+\`\`\`
+
+Use these when:
+- You need to understand the content to make decisions
+- You're writing custom analysis that can't be expressed as a pipeline
+- You're building tables with AI-enhanced columns (batch workflow)
+
 ## Common Errors & Recovery
 
 | Error | Fix |
 |-------|-----|
 | "Element not found: N" | Check \`buffer_get_structure\` for valid IDs |
-| "Buffer expired" | Re-fetch content, buffers expire in 10 min |
+| "Buffer expired" | Re-fetch content, buffers expire in 1 hour |
 | Multiple occurrences | Use \`replace_all=true\` for string edit |
 | XHTML parsing error | Check \`suggestedActions\` in error response |
 
@@ -608,7 +833,7 @@ buffer_edit(bufferId, old_string="foo", new_string="bar", replace_all=true)
 
 - IDs are **stable**: insert between 2 and 3 → new element gets id=5, element 3 unchanged
 - Use \`buffer_get_structure\` after edits to see updated structure
-- Buffers expire in 10 min (24h if modified)
+- Buffers expire in 1 hour (24h if modified)
 - XHTML syntax: \`help(topic="storage")\`
 - PlantUML: \`help(topic="plantuml")\``;
 // Topic content map

package/dist/utils/jicon-help.js.map

@@ -1 +1 @@
-{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jicon-help.js","sourceRoot":"","sources":["../../src/utils/jicon-help.ts"],"names":[],"mappings":"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"}

package/dist/utils/json-structure.d.ts

@@ -0,0 +1,121 @@
+/**
+ * JSON Structure Operations
+ *
+ * Provides unified structured access for JSON data (arrays and objects).
+ * Similar to XHTML buffer operations but for JSON data.
+ *
+ * Key design for ARRAYS:
+ * - Items get stable numeric IDs (stored in __jicon_id field)
+ * - IDs persist through insertions/deletions
+ * - Enables ID-based operations: append, insert, replace, remove
+ *
+ * Key design for OBJECTS:
+ * - Key-based access to top-level properties
+ * - No IDs needed - keys are the natural identifiers
+ */
+import type { JsonStructure } from "./content-buffer.js";
+/**
+ * Parse JSON string and build structure with IDs for array items
+ * If the JSON is an array, each item gets an ID.
+ * If it's an object with array fields, those arrays can be targeted by path.
+ */
+export declare function parseJsonStructure(jsonString: string): {
+    data: unknown;
+    structure: JsonStructure;
+    error?: string;
+};
+/**
+ * Create a new JSON buffer with structure tracking.
+ * Handles both arrays and objects:
+ * - Arrays: items get stable IDs for ID-based access
+ * - Objects: keys are extracted for key-based access
+ *
+ * @param data - Array or object to create structure for
+ * @returns content string and structure
+ */
+export declare function createJsonStructure(data: unknown): {
+    content: string;
+    structure: JsonStructure;
+};
+/**
+ * Append an item to a JSON array buffer
+ */
+export declare function appendToJsonArray(currentContent: string, currentStructure: JsonStructure, newItem: unknown): {
+    content: string;
+    structure: JsonStructure;
+    insertedId: number;
+    error?: string;
+};
+/**
+ * Insert an item into a JSON array relative to an existing item
+ */
+export declare function insertIntoJsonArray(currentContent: string, currentStructure: JsonStructure, newItem: unknown, targetId: number, position: "before" | "after"): {
+    content: string;
+    structure: JsonStructure;
+    insertedId: number;
+    error?: string;
+};
+/**
+ * Replace an item in a JSON array by ID
+ */
+export declare function replaceInJsonArray(currentContent: string, currentStructure: JsonStructure, targetId: number, newValue: unknown): {
+    content: string;
+    structure: JsonStructure;
+    error?: string;
+};
+/**
+ * Remove an item from a JSON array by ID
+ */
+export declare function removeFromJsonArray(currentContent: string, currentStructure: JsonStructure, targetId: number): {
+    content: string;
+    structure: JsonStructure;
+    error?: string;
+};
+/**
+ * Get an item from a JSON array by ID (without the internal ID field)
+ */
+export declare function getItemById(currentContent: string, currentStructure: JsonStructure, targetId: number): {
+    item: unknown;
+    error?: string;
+};
+/**
+ * Get all items from a JSON array buffer (without internal ID fields)
+ * For export/serialization
+ */
+export declare function getCleanItems(currentContent: string): {
+    items: unknown[];
+    error?: string;
+};
+/**
+ * Rebuild structure from content (for recovery/validation)
+ */
+export declare function rebuildStructure(currentContent: string): {
+    structure: JsonStructure;
+    error?: string;
+};
+/**
+ * Get a value from a JSON object by key
+ */
+export declare function getByKey(currentContent: string, currentStructure: JsonStructure, key: string): {
+    value: unknown;
+    error?: string;
+};
+/**
+ * Get items from a JSON array by index range (batch access)
+ * Returns items without internal __jicon_id fields
+ */
+export declare function getItemsByRange(currentContent: string, currentStructure: JsonStructure, start: number, count: number): {
+    items: Array<{
+        id: number;
+        item: unknown;
+    }>;
+    progress: {
+        start: number;
+        count: number;
+        total: number;
+        hasMore: boolean;
+        nextStart?: number;
+    };
+    error?: string;
+};
+//# sourceMappingURL=json-structure.d.ts.map

package/dist/utils/json-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-structure.d.ts","sourceRoot":"","sources":["../../src/utils/json-structure.ts"],"names":[],"mappings":"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"}