@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/formatting/markdownBuilder.d.ts

@@ -0,0 +1,543 @@
+/**
+ * @fileoverview Markdown builder utility for creating well-structured, semantic markdown content
+ * @module utils/formatting/markdownBuilder
+ */
+/**
+ * Utility class for building well-formatted markdown content with consistent structure.
+ *
+ * Provides a fluent API for creating markdown documents with proper spacing, hierarchy,
+ * and semantic structure. Eliminates string concatenation and ensures consistent
+ * formatting across tool response formatters. Each method appends to an internal buffer
+ * and returns `this` for chaining; call {@link MarkdownBuilder.build} to produce the
+ * final string.
+ *
+ * @example
+ * ```typescript
+ * const output = new MarkdownBuilder()
+ *   .h1('Commit Created Successfully')
+ *   .keyValue('Commit Hash', 'abc123def')
+ *   .keyValue('Author', 'John Doe')
+ *   .section('Files Changed', () => {
+ *     // `section` calls the callback immediately; builder state is mutated in place
+ *   })
+ *   .list(['file1.ts', 'file2.ts'])
+ *   .build();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using the `markdown()` factory shorthand
+ * import { markdown } from '@cyanheads/mcp-ts-core/utils/formatting';
+ *
+ * const md = markdown()
+ *   .h2('Results')
+ *   .table(['Name', 'Status'], [['foo', 'ok'], ['bar', 'fail']])
+ *   .build();
+ * ```
+ */
+export declare class MarkdownBuilder {
+    private sections;
+    /**
+     * Add a level 1 heading (`# text`).
+     *
+     * @param text - The heading text
+     * @param emoji - Optional emoji prepended before the text with a space
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().h1('Report').build();           // '# Report'
+     * markdown().h1('Report', '📋').build();     // '# 📋 Report'
+     * ```
+     */
+    h1(text: string, emoji?: string): this;
+    /**
+     * Add a level 2 heading (`## text`).
+     *
+     * @param text - The heading text
+     * @param emoji - Optional emoji prepended before the text with a space
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().h2('Section').build();   // '## Section'
+     * ```
+     */
+    h2(text: string, emoji?: string): this;
+    /**
+     * Add a level 3 heading (`### text`).
+     *
+     * @param text - The heading text
+     * @param emoji - Optional emoji prepended before the text with a space
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().h3('Subsection').build();   // '### Subsection'
+     * ```
+     */
+    h3(text: string, emoji?: string): this;
+    /**
+     * Add a level 4 heading (`#### text`).
+     *
+     * @param text - The heading text
+     * @param emoji - Optional emoji prepended before the text with a space
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().h4('Detail').build();   // '#### Detail'
+     * ```
+     */
+    h4(text: string, emoji?: string): this;
+    /**
+     * Add a bold key-value pair on a single line (`**key:** value`).
+     * `null` values are rendered as the string `'null'`.
+     *
+     * @param key - The key label, rendered in bold
+     * @param value - The value; `null` renders as `'null'`
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().keyValue('Status', 'active').build();   // '**Status:** active'
+     * markdown().keyValue('Count', 42).build();          // '**Count:** 42'
+     * markdown().keyValue('Flag', null).build();         // '**Flag:** null'
+     * ```
+     */
+    keyValue(key: string, value: string | number | boolean | null): this;
+    /**
+     * Add a plain (unbolded) key-value pair on a single line (`key: value`).
+     * Use when less visual emphasis is desired compared to {@link keyValue}.
+     * `null` values are rendered as the string `'null'`.
+     *
+     * @param key - The key label, rendered without formatting
+     * @param value - The value; `null` renders as `'null'`
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().keyValuePlain('host', 'localhost').build();   // 'host: localhost'
+     * ```
+     */
+    keyValuePlain(key: string, value: string | number | boolean | null): this;
+    /**
+     * Add a bulleted (`-`) or numbered list. Empty arrays are silently ignored.
+     *
+     * @param items - Array of string items to render
+     * @param ordered - When `true`, renders a numbered list (`1.`, `2.`, …); defaults to `false` (bulleted)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().list(['alpha', 'beta', 'gamma']).build();
+     * // - alpha
+     * // - beta
+     * // - gamma
+     *
+     * markdown().list(['first', 'second'], true).build();
+     * // 1. first
+     * // 2. second
+     * ```
+     */
+    list(items: string[], ordered?: boolean): this;
+    /**
+     * Add a fenced code block with optional syntax highlighting.
+     *
+     * @param content - The code content placed verbatim inside the fence
+     * @param language - Language identifier for syntax highlighting (e.g. `'typescript'`, `'json'`, `'diff'`); defaults to no language
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().codeBlock('const x = 1;', 'typescript').build();
+     * // ```typescript
+     * // const x = 1;
+     * // ```
+     * ```
+     */
+    codeBlock(content: string, language?: string): this;
+    /**
+     * Append inline code wrapped in single backticks (`` `code` ``).
+     * No trailing newline is added — suitable for inline use within a sentence.
+     *
+     * @param code - The code text to wrap
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().text('Call ').inlineCode('build()').text(' when done.').build();
+     * // Call `build()` when done.
+     * ```
+     */
+    inlineCode(code: string): this;
+    /**
+     * Add a paragraph of text followed by two newlines.
+     *
+     * @param text - The paragraph content
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().paragraph('Hello world.').paragraph('Second paragraph.').build();
+     * // Hello world.
+     * //
+     * // Second paragraph.
+     * ```
+     */
+    paragraph(text: string): this;
+    /**
+     * Add a blockquote. Each line of `text` is prefixed with `> `.
+     *
+     * @param text - The quoted text; multi-line strings are handled correctly
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().blockquote('Line one\nLine two').build();
+     * // > Line one
+     * // > Line two
+     * ```
+     */
+    blockquote(text: string): this;
+    /**
+     * Add a horizontal rule.
+     * @returns this builder for chaining
+     */
+    hr(): this;
+    /**
+     * Append an inline markdown link (`[text](url)`).
+     * No trailing newline is added — suitable for inline use within a sentence.
+     *
+     * @param text - The visible link label
+     * @param url - The link target URL
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().text('See ').link('the docs', 'https://example.com').text(' for details.').build();
+     * // See [the docs](https://example.com) for details.
+     * ```
+     */
+    link(text: string, url: string): this;
+    /**
+     * Add a GFM-style table. Returns without modification if `headers` or `rows` is empty.
+     * All separator cells use `---`; no alignment syntax is applied.
+     *
+     * @param headers - Column header labels
+     * @param rows - Data rows; each inner array should have the same length as `headers`
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().table(['Name', 'Status'], [['foo', 'ok'], ['bar', 'fail']]).build();
+     * // | Name | Status |
+     * // | --- | --- |
+     * // | foo | ok |
+     * // | bar | fail |
+     * ```
+     */
+    table(headers: string[], rows: string[][]): this;
+    /**
+     * Add a headed section by rendering a heading then immediately invoking a callback.
+     * The callback is called synchronously; any builder calls inside it mutate the same
+     * instance. Defaults to heading level 2 when no level is provided.
+     *
+     * @param title - The section heading text
+     * @param levelOrContent - Heading level (`2`|`3`|`4`) or callback when using the two-arg overload
+     * @param content - Callback that appends section body content (required when `level` is provided)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * const md = markdown();
+     * md.section('Files Changed', () => {
+     *   md.list(['file1.ts', 'file2.ts']);
+     * });
+     * // ## Files Changed
+     * //
+     * // - file1.ts
+     * // - file2.ts
+     *
+     * md.section('Details', 3, () => {
+     *   md.paragraph('Nested at level 3.');
+     * });
+     * // ### Details
+     * //
+     * // Nested at level 3.
+     * ```
+     */
+    section(title: string, content: () => void): this;
+    section(title: string, level: 2 | 3 | 4, content: () => void): this;
+    /**
+     * Add a collapsible `<details>`/`<summary>` HTML block.
+     * The `summary` is always visible; `details` content is collapsed by default.
+     * Not all markdown renderers support this — GitHub and GitLab do.
+     *
+     * @param summary - The always-visible summary label
+     * @param details - The collapsible body content (plain text or markdown)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().details('Show stack trace', 'Error: something went wrong\n  at foo.ts:10').build();
+     * // <details>
+     * // <summary>Show stack trace</summary>
+     * //
+     * // Error: something went wrong
+     * //   at foo.ts:10
+     * //
+     * // </details>
+     * ```
+     */
+    details(summary: string, details: string): this;
+    /**
+     * Add a status/alert box (GitHub/GitLab style).
+     * Renders as a highlighted blockquote with an icon.
+     *
+     * Supported types:
+     * - 'note': 📝 Neutral information
+     * - 'tip': 💡 Helpful suggestions
+     * - 'important': ❗ Critical information
+     * - 'warning': ⚠️ Warning/caution
+     * - 'caution': 🚨 Danger/destructive action
+     *
+     * @param type - Alert type
+     * @param content - Alert content (can be multi-line)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.alert('warning', 'This operation cannot be undone!');
+     * // Renders: > [!WARNING]
+     * //          > This operation cannot be undone!
+     * ```
+     */
+    alert(type: 'note' | 'tip' | 'important' | 'warning' | 'caution', content: string): this;
+    /**
+     * Add a task list with checkboxes (GitHub style).
+     *
+     * @param items - Array of tasks with checked status
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.taskList([
+     *   { checked: true, text: 'Complete setup' },
+     *   { checked: false, text: 'Run tests' },
+     * ]);
+     * // Renders: - [x] Complete setup
+     * //          - [ ] Run tests
+     * ```
+     */
+    taskList(items: Array<{
+        checked: boolean;
+        text: string;
+    }>): this;
+    /**
+     * Add an image with alt text and optional title.
+     *
+     * @param altText - Alternative text for the image
+     * @param url - Image URL
+     * @param title - Optional title (shown on hover)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.image('Architecture diagram', '/assets/diagram.png', 'System Architecture');
+     * // Renders: ![Architecture diagram](/assets/diagram.png "System Architecture")
+     * ```
+     */
+    image(altText: string, url: string, title?: string): this;
+    /**
+     * Add strikethrough text.
+     *
+     * @param text - Text to strike through
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('Price: ').strikethrough('$100').text(' $80');
+     * // Renders: Price: ~~$100~~ $80
+     * ```
+     */
+    strikethrough(text: string): this;
+    /**
+     * Add a `diff`-language fenced code block showing additions and deletions.
+     * Rendering order: context lines (two-space indent) → deletions (`- ` prefix) → additions (`+ ` prefix).
+     * If all three arrays are empty or omitted, nothing is appended.
+     *
+     * @param changes - Line arrays for the diff
+     * @param changes.context - Unchanged context lines (rendered with two-space indent)
+     * @param changes.deletions - Removed lines (rendered with `- ` prefix)
+     * @param changes.additions - Added lines (rendered with `+ ` prefix)
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().diff({
+     *   context: ['// Configuration'],
+     *   deletions: ['const oldFeature = false;'],
+     *   additions: ['const newFeature = true;'],
+     * }).build();
+     * // ```diff
+     * //   // Configuration
+     * // - const oldFeature = false;
+     * // + const newFeature = true;
+     * // ```
+     * ```
+     */
+    diff(changes: {
+        additions?: string[];
+        deletions?: string[];
+        context?: string[];
+    }): this;
+    /**
+     * Add a badge/shield (uses shields.io style).
+     *
+     * @param label - Badge label (left side)
+     * @param message - Badge message (right side)
+     * @param color - Optional color (e.g., 'green', 'red', 'blue', 'yellow')
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.badge('build', 'passing', 'green');
+     * // Renders: ![build: passing](https://img.shields.io/badge/build-passing-green)
+     * ```
+     */
+    badge(label: string, message: string, color?: string): this;
+    /**
+     * Add bold text.
+     *
+     * @param text - Text to make bold
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('This is ').bold('important').text(' information.');
+     * // Renders: This is **important** information.
+     * ```
+     */
+    bold(text: string): this;
+    /**
+     * Add italic text.
+     *
+     * @param text - Text to make italic
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.text('This is ').italic('emphasized').text('.');
+     * // Renders: This is *emphasized*.
+     * ```
+     */
+    italic(text: string): this;
+    /**
+     * Add bold and italic text.
+     *
+     * @param text - Text to make bold and italic
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.boldItalic('Very important');
+     * // Renders: ***Very important***
+     * ```
+     */
+    boldItalic(text: string): this;
+    /**
+     * Append a raw markdown string directly to the buffer without any transformation.
+     * Use this for custom formatting not covered by other methods.
+     *
+     * @param markdown - Raw markdown string appended verbatim
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().raw('> custom blockquote\n\n').build();
+     * // > custom blockquote
+     * ```
+     */
+    raw(markdown: string): this;
+    /**
+     * Add a blank line for spacing.
+     * @returns this builder for chaining
+     */
+    blankLine(): this;
+    /**
+     * Append plain text without any markdown formatting or implicit line breaks.
+     * Useful for building inline content by interleaving with methods like
+     * {@link bold}, {@link italic}, {@link inlineCode}, and {@link link}.
+     *
+     * @param text - The text to append verbatim
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * markdown().text('Result: ').bold('42').text(' items found.').build();
+     * // Result: **42** items found.
+     * ```
+     */
+    text(text: string): this;
+    /**
+     * Conditionally append content. The callback is invoked synchronously only when
+     * `condition` is `true`; otherwise the builder is returned unchanged.
+     *
+     * @param condition - When `true`, the callback is invoked
+     * @param content - Callback that appends content to this builder
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * md.when(files.length > 0, () => {
+     *   md.h2('Files Changed').list(files);
+     * });
+     * ```
+     */
+    when(condition: boolean, content: () => void): this;
+    /**
+     * Concatenate all buffered sections and return the final markdown string.
+     * Leading and trailing whitespace is trimmed so documents always end cleanly.
+     * The builder instance is NOT reset — call {@link reset} explicitly if reuse is needed.
+     *
+     * @returns The complete markdown document as a trimmed string
+     *
+     * @example
+     * ```typescript
+     * const output = markdown().h1('Hello').paragraph('World').build();
+     * // '# Hello\n\nWorld'
+     * ```
+     */
+    build(): string;
+    /**
+     * Clear all buffered content so the builder can be reused for a new document.
+     *
+     * @returns this builder for chaining
+     *
+     * @example
+     * ```typescript
+     * const md = markdown().h1('Draft');
+     * md.reset().h1('Final').build();   // '# Final'
+     * ```
+     */
+    reset(): this;
+}
+/**
+ * Factory function that creates a new {@link MarkdownBuilder} instance.
+ * Prefer this over `new MarkdownBuilder()` for concise call-site syntax.
+ *
+ * @returns A fresh, empty `MarkdownBuilder`
+ *
+ * @example
+ * ```typescript
+ * import { markdown } from '@cyanheads/mcp-ts-core/utils/formatting';
+ *
+ * const output = markdown()
+ *   .h1('Summary')
+ *   .keyValue('Total', 5)
+ *   .build();
+ * ```
+ */
+export declare function markdown(): MarkdownBuilder;
+//# sourceMappingURL=markdownBuilder.d.ts.map

package/dist/utils/formatting/markdownBuilder.d.ts.map

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