@specforge/mcp 1.5.3 → 1.6.0

package/dist/lib/format.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Format Utility Module
+ *
+ * Provides utilities for formatting response data as JSON or TOON format.
+ * TOON (Token Optimized Object Notation) is a human-readable format that
+ * uses fewer tokens than JSON while maintaining semantic clarity.
+ *
+ * @see MCI-014-03-format-utility-module
+ */
+/**
+ * Supported output formats for response data
+ */
+export type OutputFormat = 'json' | 'toon';
+/**
+ * Format response data as JSON or TOON.
+ *
+ * JSON format (default) returns the original data object unchanged,
+ * allowing the MCP protocol to handle JSON serialization.
+ *
+ * TOON format returns a human-readable string optimized for token efficiency.
+ *
+ * @param data - The data to format
+ * @param format - Output format ('json' or 'toon'), defaults to 'json'
+ * @returns Formatted data - original object for JSON, string for TOON
+ *
+ * @example
+ * ```typescript
+ * // JSON (default) - returns unchanged
+ * formatResponse({ id: "123" }) // returns { id: "123" }
+ *
+ * // TOON - returns formatted string
+ * formatResponse({ id: "123" }, 'toon')
+ * // returns "id: 123"
+ *
+ * // Complex objects
+ * formatResponse({
+ *   ticket: { id: "T-001", title: "Task", status: "done" }
+ * }, 'toon')
+ * // returns:
+ * // ticket.id: T-001
+ * // ticket.title: Task
+ * // ticket.status: done
+ * ```
+ */
+export declare function formatResponse<T>(data: T, format?: OutputFormat): string | T;
+/**
+ * Check if a format string is a valid OutputFormat
+ *
+ * @param format - Value to check
+ * @returns True if format is 'json' or 'toon'
+ *
+ * @example
+ * ```typescript
+ * isValidFormat('json')  // true
+ * isValidFormat('toon')  // true
+ * isValidFormat('xml')   // false
+ * isValidFormat(null)    // false
+ * ```
+ */
+export declare function isValidFormat(format: unknown): format is OutputFormat;
+/**
+ * Extract and validate format from tool arguments
+ *
+ * Returns the format if valid, otherwise defaults to 'json'.
+ *
+ * @param args - Tool arguments object
+ * @returns Validated OutputFormat, defaults to 'json'
+ *
+ * @example
+ * ```typescript
+ * getFormatFromArgs({ format: 'toon' })  // 'toon'
+ * getFormatFromArgs({ format: 'json' })  // 'json'
+ * getFormatFromArgs({})                  // 'json'
+ * getFormatFromArgs({ format: 'xml' })   // 'json' (invalid, falls back)
+ * ```
+ */
+export declare function getFormatFromArgs(args: Record<string, unknown>): OutputFormat;
+/**
+ * Format an array of items with optional TOON tabular formatting
+ *
+ * For TOON format, arrays with homogeneous objects can be rendered
+ * in a more compact tabular format. This is useful for lists of
+ * tickets, epics, etc.
+ *
+ * @param items - Array of items to format
+ * @param format - Output format
+ * @returns Formatted items
+ *
+ * @example
+ * ```typescript
+ * formatArrayResponse([
+ *   { id: '1', status: 'done' },
+ *   { id: '2', status: 'todo' }
+ * ], 'toon')
+ * // Returns:
+ * // []:
+ * //   - id: 1
+ * //     status: done
+ * //   - id: 2
+ * //     status: todo
+ * ```
+ */
+export declare function formatArrayResponse<T>(items: T[], format?: OutputFormat): string | T[];
+/**
+ * Format an error response with consistent structure
+ *
+ * @param error - Error message or Error object
+ * @param code - Optional error code
+ * @param format - Output format
+ * @returns Formatted error response
+ *
+ * @example
+ * ```typescript
+ * formatErrorResponse('Not found', 'NOT_FOUND', 'toon')
+ * // Returns:
+ * // error: Not found
+ * // code: NOT_FOUND
+ * ```
+ */
+export declare function formatErrorResponse(error: string | Error, code?: string, format?: OutputFormat): string | {
+    error: string;
+    code?: string;
+};
+/**
+ * Format a success response with optional data
+ *
+ * @param message - Success message
+ * @param data - Optional additional data
+ * @param format - Output format
+ * @returns Formatted success response
+ *
+ * @example
+ * ```typescript
+ * formatSuccessResponse('Created', { id: '123' }, 'toon')
+ * // Returns:
+ * // success: true
+ * // message: Created
+ * // id: 123
+ * ```
+ */
+export declare function formatSuccessResponse<T extends Record<string, unknown>>(message: string, data?: T, format?: OutputFormat): string | {
+    success: true;
+    message: string;
+} & T;
+//# sourceMappingURL=format.d.ts.map

package/dist/lib/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/lib/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAmE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAE,YAAqB,GAAG,MAAM,GAAG,CAAC,CAcpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,YAAY,CAErE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAM7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,GAAE,YAAqB,GAAG,MAAM,GAAG,CAAC,EAAE,CAE9F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,KAAK,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,MAAM,GAAE,YAAqB,GAC5B,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAO3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,CAAC,EACR,MAAM,GAAE,YAAqB,GAC5B,MAAM,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC,CAGjD"}

package/dist/lib/format.js

@@ -0,0 +1,227 @@
+/**
+ * Format Utility Module
+ *
+ * Provides utilities for formatting response data as JSON or TOON format.
+ * TOON (Token Optimized Object Notation) is a human-readable format that
+ * uses fewer tokens than JSON while maintaining semantic clarity.
+ *
+ * @see MCI-014-03-format-utility-module
+ */
+import { encode as toonEncode } from '@toon-format/toon';
+/**
+ * Default TOON formatting options optimized for SpecForge data
+ *
+ * These settings balance readability with token efficiency:
+ * - indent: 2 spaces for clean nesting
+ * - keyFolding: 'safe' collapses single-key chains (e.g., data.id instead of nested)
+ */
+const TOON_OPTIONS = {
+    indent: 2,
+    keyFolding: 'safe',
+};
+/**
+ * Pre-process data for optimal TOON output.
+ *
+ * This function handles:
+ * - Removing undefined values from objects
+ * - Recursively processing nested structures
+ * - Preserving null values (TOON represents these as ~)
+ * - Handling arrays with mixed or complex content
+ *
+ * @param data - Data to preprocess
+ * @returns Preprocessed data ready for TOON encoding
+ *
+ * @example
+ * ```typescript
+ * preprocessForToon({ a: 1, b: undefined, c: null })
+ * // Returns: { a: 1, c: null } (undefined removed, null preserved)
+ *
+ * preprocessForToon({ nested: { deep: { value: "test" } } })
+ * // Returns the same structure, recursively processed
+ * ```
+ */
+function preprocessForToon(data) {
+    // Handle null/undefined at top level
+    if (data === null || data === undefined) {
+        return data;
+    }
+    // Handle arrays - recursively process each element
+    if (Array.isArray(data)) {
+        return data.map(preprocessForToon);
+    }
+    // Handle objects - filter undefined and recursively process
+    if (typeof data === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            // Skip undefined values entirely
+            if (value === undefined) {
+                continue;
+            }
+            // Recursively process nested values
+            result[key] = preprocessForToon(value);
+        }
+        return result;
+    }
+    // Return primitives unchanged
+    return data;
+}
+/**
+ * Format response data as JSON or TOON.
+ *
+ * JSON format (default) returns the original data object unchanged,
+ * allowing the MCP protocol to handle JSON serialization.
+ *
+ * TOON format returns a human-readable string optimized for token efficiency.
+ *
+ * @param data - The data to format
+ * @param format - Output format ('json' or 'toon'), defaults to 'json'
+ * @returns Formatted data - original object for JSON, string for TOON
+ *
+ * @example
+ * ```typescript
+ * // JSON (default) - returns unchanged
+ * formatResponse({ id: "123" }) // returns { id: "123" }
+ *
+ * // TOON - returns formatted string
+ * formatResponse({ id: "123" }, 'toon')
+ * // returns "id: 123"
+ *
+ * // Complex objects
+ * formatResponse({
+ *   ticket: { id: "T-001", title: "Task", status: "done" }
+ * }, 'toon')
+ * // returns:
+ * // ticket.id: T-001
+ * // ticket.title: Task
+ * // ticket.status: done
+ * ```
+ */
+export function formatResponse(data, format = 'json') {
+    if (format === 'json') {
+        return data;
+    }
+    try {
+        // Preprocess data to handle undefined values and complex structures
+        const processed = preprocessForToon(data);
+        return toonEncode(processed, TOON_OPTIONS);
+    }
+    catch (error) {
+        // Fallback to JSON on TOON encoding errors
+        console.error('TOON formatting failed, falling back to JSON:', error);
+        return data;
+    }
+}
+/**
+ * Check if a format string is a valid OutputFormat
+ *
+ * @param format - Value to check
+ * @returns True if format is 'json' or 'toon'
+ *
+ * @example
+ * ```typescript
+ * isValidFormat('json')  // true
+ * isValidFormat('toon')  // true
+ * isValidFormat('xml')   // false
+ * isValidFormat(null)    // false
+ * ```
+ */
+export function isValidFormat(format) {
+    return format === 'json' || format === 'toon';
+}
+/**
+ * Extract and validate format from tool arguments
+ *
+ * Returns the format if valid, otherwise defaults to 'json'.
+ *
+ * @param args - Tool arguments object
+ * @returns Validated OutputFormat, defaults to 'json'
+ *
+ * @example
+ * ```typescript
+ * getFormatFromArgs({ format: 'toon' })  // 'toon'
+ * getFormatFromArgs({ format: 'json' })  // 'json'
+ * getFormatFromArgs({})                  // 'json'
+ * getFormatFromArgs({ format: 'xml' })   // 'json' (invalid, falls back)
+ * ```
+ */
+export function getFormatFromArgs(args) {
+    const format = args?.format;
+    if (isValidFormat(format)) {
+        return format;
+    }
+    return 'json';
+}
+/**
+ * Format an array of items with optional TOON tabular formatting
+ *
+ * For TOON format, arrays with homogeneous objects can be rendered
+ * in a more compact tabular format. This is useful for lists of
+ * tickets, epics, etc.
+ *
+ * @param items - Array of items to format
+ * @param format - Output format
+ * @returns Formatted items
+ *
+ * @example
+ * ```typescript
+ * formatArrayResponse([
+ *   { id: '1', status: 'done' },
+ *   { id: '2', status: 'todo' }
+ * ], 'toon')
+ * // Returns:
+ * // []:
+ * //   - id: 1
+ * //     status: done
+ * //   - id: 2
+ * //     status: todo
+ * ```
+ */
+export function formatArrayResponse(items, format = 'json') {
+    return formatResponse(items, format);
+}
+/**
+ * Format an error response with consistent structure
+ *
+ * @param error - Error message or Error object
+ * @param code - Optional error code
+ * @param format - Output format
+ * @returns Formatted error response
+ *
+ * @example
+ * ```typescript
+ * formatErrorResponse('Not found', 'NOT_FOUND', 'toon')
+ * // Returns:
+ * // error: Not found
+ * // code: NOT_FOUND
+ * ```
+ */
+export function formatErrorResponse(error, code, format = 'json') {
+    const errorMessage = error instanceof Error ? error.message : error;
+    const response = { error: errorMessage };
+    if (code) {
+        response.code = code;
+    }
+    return formatResponse(response, format);
+}
+/**
+ * Format a success response with optional data
+ *
+ * @param message - Success message
+ * @param data - Optional additional data
+ * @param format - Output format
+ * @returns Formatted success response
+ *
+ * @example
+ * ```typescript
+ * formatSuccessResponse('Created', { id: '123' }, 'toon')
+ * // Returns:
+ * // success: true
+ * // message: Created
+ * // id: 123
+ * ```
+ */
+export function formatSuccessResponse(message, data, format = 'json') {
+    const response = { success: true, message, ...data };
+    return formatResponse(response, format);
+}
+//# sourceMappingURL=format.js.map

package/dist/lib/format.js.map

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

package/dist/lib/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Library Utilities
+ *
+ * Exports shared utility modules for the MCP server.
+ */
+export { type OutputFormat, formatResponse, formatArrayResponse, formatErrorResponse, formatSuccessResponse, isValidFormat, getFormatFromArgs, } from './format.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,YAAY,EACjB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/lib/index.js

@@ -0,0 +1,7 @@
+/**
+ * Library Utilities
+ *
+ * Exports shared utility modules for the MCP server.
+ */
+export { formatResponse, formatArrayResponse, formatErrorResponse, formatSuccessResponse, isValidFormat, getFormatFromArgs, } from './format.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAEL,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/lib/response.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Response Mode Utilities
+ *
+ * Client-side utilities for response mode handling in write operations.
+ * Implements MCI-057: Response Modes for Write Operations
+ *
+ * Response modes control the verbosity of create/update operation responses:
+ * - 'full': Complete object (~500 tokens) - default
+ * - 'minimal': id, number, title, message (~50 tokens)
+ * - 'id-only': id and number only (~20 tokens)
+ */
+/**
+ * Response mode for write operations
+ */
+export type ResponseMode = 'full' | 'minimal' | 'id-only';
+/**
+ * Valid response modes
+ */
+export declare const RESPONSE_MODES: ResponseMode[];
+/**
+ * Minimal response for write operations
+ */
+export interface MinimalResponse {
+    id: string;
+    ticketNumber?: number;
+    epicNumber?: number;
+    title: string;
+    message: string;
+}
+/**
+ * ID-only response for write operations
+ */
+export interface IdOnlyResponse {
+    id: string;
+    ticketNumber?: number;
+    epicNumber?: number;
+}
+/**
+ * Check if a value is a valid response mode
+ */
+export declare function isValidResponseMode(value: unknown): value is ResponseMode;
+/**
+ * Parse response mode from tool arguments, defaulting to 'full'
+ *
+ * @param args - Tool arguments object
+ * @returns Validated ResponseMode, defaults to 'full'
+ *
+ * @example
+ * ```typescript
+ * getResponseModeFromArgs({ responseMode: 'minimal' })  // 'minimal'
+ * getResponseModeFromArgs({ responseMode: 'id-only' })  // 'id-only'
+ * getResponseModeFromArgs({})                           // 'full'
+ * getResponseModeFromArgs({ responseMode: 'invalid' }) // 'full' (invalid, falls back)
+ * ```
+ */
+export declare function getResponseModeFromArgs(args: Record<string, unknown>): ResponseMode;
+/**
+ * Format a write operation response based on mode.
+ *
+ * This reduces token usage when full details aren't needed:
+ * - 'full': Returns unchanged (~500 tokens)
+ * - 'minimal': Returns id, numbers, title, message (~50 tokens)
+ * - 'id-only': Returns id and numbers only (~20 tokens)
+ *
+ * @param entity - Full entity object from API response
+ * @param mode - Response mode
+ * @param message - Success message for minimal mode
+ * @returns Formatted response based on mode
+ *
+ * @example
+ * ```typescript
+ * // Full mode (default)
+ * formatWriteResponse(ticket, 'full', 'Created')
+ * // Returns: { id, title, status, description, ... }
+ *
+ * // Minimal mode
+ * formatWriteResponse(ticket, 'minimal', 'Ticket created')
+ * // Returns: { id: 'xyz', ticketNumber: 1, title: 'My Ticket', message: 'Ticket created' }
+ *
+ * // ID-only mode
+ * formatWriteResponse(ticket, 'id-only', 'Created')
+ * // Returns: { id: 'xyz', ticketNumber: 1 }
+ * ```
+ */
+export declare function formatWriteResponse<T extends {
+    id: string;
+    title?: string;
+    ticket?: {
+        id: string;
+        title: string;
+    };
+    epic?: {
+        id: string;
+        title: string;
+    };
+    specification?: {
+        id: string;
+        title: string;
+    };
+}>(entity: T, mode: ResponseMode, message: string): T | MinimalResponse | IdOnlyResponse;
+/**
+ * Format multiple write operation responses based on mode.
+ *
+ * @param entities - Array of entity objects
+ * @param mode - Response mode
+ * @param message - Success message template for minimal mode
+ * @returns Array of formatted responses
+ *
+ * @example
+ * ```typescript
+ * formatWriteResponses(tickets, 'minimal', 'Ticket created')
+ * // Returns: [{ id, ticketNumber, title, message }, ...]
+ * ```
+ */
+export declare function formatWriteResponses<T extends {
+    id: string;
+    title?: string;
+}>(entities: T[], mode: ResponseMode, message: string): Array<T | MinimalResponse | IdOnlyResponse>;
+//# sourceMappingURL=response.d.ts.map

package/dist/lib/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/lib/response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,YAAY,EAAmC,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,YAAY,CAMd;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,aAAa,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAErK,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,GACd,CAAC,GAAG,eAAe,GAAG,cAAc,CAwBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAExC,QAAQ,EAAE,CAAC,EAAE,EACb,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,GACd,KAAK,CAAC,CAAC,GAAG,eAAe,GAAG,cAAc,CAAC,CAE7C"}

package/dist/lib/response.js

@@ -0,0 +1,123 @@
+/**
+ * Response Mode Utilities
+ *
+ * Client-side utilities for response mode handling in write operations.
+ * Implements MCI-057: Response Modes for Write Operations
+ *
+ * Response modes control the verbosity of create/update operation responses:
+ * - 'full': Complete object (~500 tokens) - default
+ * - 'minimal': id, number, title, message (~50 tokens)
+ * - 'id-only': id and number only (~20 tokens)
+ */
+/**
+ * Valid response modes
+ */
+export const RESPONSE_MODES = ['full', 'minimal', 'id-only'];
+/**
+ * Check if a value is a valid response mode
+ */
+export function isValidResponseMode(value) {
+    return typeof value === 'string' && RESPONSE_MODES.includes(value);
+}
+/**
+ * Parse response mode from tool arguments, defaulting to 'full'
+ *
+ * @param args - Tool arguments object
+ * @returns Validated ResponseMode, defaults to 'full'
+ *
+ * @example
+ * ```typescript
+ * getResponseModeFromArgs({ responseMode: 'minimal' })  // 'minimal'
+ * getResponseModeFromArgs({ responseMode: 'id-only' })  // 'id-only'
+ * getResponseModeFromArgs({})                           // 'full'
+ * getResponseModeFromArgs({ responseMode: 'invalid' }) // 'full' (invalid, falls back)
+ * ```
+ */
+export function getResponseModeFromArgs(args) {
+    const mode = args?.responseMode;
+    if (isValidResponseMode(mode)) {
+        return mode;
+    }
+    return 'full';
+}
+/**
+ * Extract number field from entity result
+ */
+function extractNumber(entity) {
+    const result = {};
+    if (typeof entity.ticketNumber === 'number') {
+        result.ticketNumber = entity.ticketNumber;
+    }
+    if (typeof entity.epicNumber === 'number') {
+        result.epicNumber = entity.epicNumber;
+    }
+    return result;
+}
+/**
+ * Format a write operation response based on mode.
+ *
+ * This reduces token usage when full details aren't needed:
+ * - 'full': Returns unchanged (~500 tokens)
+ * - 'minimal': Returns id, numbers, title, message (~50 tokens)
+ * - 'id-only': Returns id and numbers only (~20 tokens)
+ *
+ * @param entity - Full entity object from API response
+ * @param mode - Response mode
+ * @param message - Success message for minimal mode
+ * @returns Formatted response based on mode
+ *
+ * @example
+ * ```typescript
+ * // Full mode (default)
+ * formatWriteResponse(ticket, 'full', 'Created')
+ * // Returns: { id, title, status, description, ... }
+ *
+ * // Minimal mode
+ * formatWriteResponse(ticket, 'minimal', 'Ticket created')
+ * // Returns: { id: 'xyz', ticketNumber: 1, title: 'My Ticket', message: 'Ticket created' }
+ *
+ * // ID-only mode
+ * formatWriteResponse(ticket, 'id-only', 'Created')
+ * // Returns: { id: 'xyz', ticketNumber: 1 }
+ * ```
+ */
+export function formatWriteResponse(entity, mode, message) {
+    // Handle nested entity structures (update_ticket returns { ticket: {...} })
+    const actualEntity = entity.ticket || entity.epic || entity.specification || entity;
+    const entityRecord = actualEntity;
+    switch (mode) {
+        case 'id-only':
+            return {
+                id: entityRecord.id,
+                ...extractNumber(entityRecord),
+            };
+        case 'minimal':
+            return {
+                id: entityRecord.id,
+                ...extractNumber(entityRecord),
+                title: entityRecord.title || '',
+                message,
+            };
+        case 'full':
+        default:
+            return entity;
+    }
+}
+/**
+ * Format multiple write operation responses based on mode.
+ *
+ * @param entities - Array of entity objects
+ * @param mode - Response mode
+ * @param message - Success message template for minimal mode
+ * @returns Array of formatted responses
+ *
+ * @example
+ * ```typescript
+ * formatWriteResponses(tickets, 'minimal', 'Ticket created')
+ * // Returns: [{ id, ticketNumber, title, message }, ...]
+ * ```
+ */
+export function formatWriteResponses(entities, mode, message) {
+    return entities.map((entity) => formatWriteResponse(entity, mode, message));
+}
+//# sourceMappingURL=response.js.map

package/dist/lib/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/lib/response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAsB7E;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAA6B;IAE7B,MAAM,IAAI,GAAG,IAAI,EAAE,YAAY,CAAC;IAChC,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CACpB,MAA+B;IAE/B,MAAM,MAAM,GAAmD,EAAE,CAAC;IAElE,IAAI,OAAO,MAAM,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACxC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,mBAAmB,CAGjC,MAAS,EACT,IAAkB,EAClB,OAAe;IAEf,4EAA4E;IAC5E,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC;IACpF,MAAM,YAAY,GAAG,YAAuC,CAAC;IAE7D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,SAAS;YACZ,OAAO;gBACL,EAAE,EAAE,YAAY,CAAC,EAAY;gBAC7B,GAAG,aAAa,CAAC,YAAY,CAAC;aAC/B,CAAC;QAEJ,KAAK,SAAS;YACZ,OAAO;gBACL,EAAE,EAAE,YAAY,CAAC,EAAY;gBAC7B,GAAG,aAAa,CAAC,YAAY,CAAC;gBAC9B,KAAK,EAAG,YAAY,CAAC,KAAgB,IAAI,EAAE;gBAC3C,OAAO;aACR,CAAC;QAEJ,KAAK,MAAM,CAAC;QACZ;YACE,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAGlC,QAAa,EACb,IAAkB,EAClB,OAAe;IAEf,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC"}

package/dist/patterns/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pattern Inheritance Module
+ *
+ * Exports pattern resolution functions for the SpecForge MCP.
+ *
+ * @see MCI-030-05-pattern-inheritance-resolver
+ */
+export { type ResolvedPatterns, type PatternOverride, type PatternOverrideReport, type PatternResolutionInput, resolvePatterns, resolvePatternsWithCache, getPatternOverrides, flattenCodeStandards, flattenSharedPatterns, invalidatePatternCache, invalidateAllPatternCaches, getPatternCacheSize, } from './inheritance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/patterns/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAE3B,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EAEnB,oBAAoB,EACpB,qBAAqB,EAErB,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}