@syrin/cli 1.3.0

package/dist/utils/json-file-saver.js

@@ -0,0 +1,81 @@
+/**
+ * Utilities for saving large JSON data to external files.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Save JSON data to a file.
+ * Returns the file path.
+ */
+export function saveJSONToFile(data, toolName, outputDir) {
+    const dir = outputDir || path.join(os.tmpdir(), 'syrin-json-exports');
+    // Ensure directory exists
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Sanitize toolName to ensure valid filename
+    // Remove or replace invalid filesystem characters: / \ : * ? " < > |
+    let sanitizedToolName = toolName
+        .replace(/[/\\:*?"<>|]/g, '-') // Replace invalid chars with hyphen
+        .replace(/-+/g, '-') // Collapse repeated hyphens
+        .trim(); // Remove leading/trailing whitespace
+    // Ensure non-empty and limit length
+    if (!sanitizedToolName || sanitizedToolName.length === 0) {
+        sanitizedToolName = 'tool';
+    }
+    else if (sanitizedToolName.length > 100) {
+        sanitizedToolName = sanitizedToolName.substring(0, 100);
+    }
+    // Generate filename with timestamp
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const filename = `${sanitizedToolName}-${timestamp}.json`;
+    const filePath = path.join(dir, filename);
+    // Parse if data is already a JSON string to avoid double-escaping
+    let parsedData = data;
+    if (typeof data === 'string') {
+        try {
+            // Try to parse as JSON - if it's already a JSON string, parse it first
+            parsedData = JSON.parse(data);
+        }
+        catch {
+            // If parsing fails, it's not JSON, keep as string
+            parsedData = data;
+        }
+    }
+    // Write JSON with pretty formatting (no escape sequences)
+    const jsonString = JSON.stringify(parsedData, null, 2);
+    fs.writeFileSync(filePath, jsonString, 'utf-8');
+    return filePath;
+}
+/**
+ * Get the size of a file in human-readable format.
+ */
+export function getFileSize(filePath) {
+    try {
+        const stats = fs.statSync(filePath);
+        const bytes = stats.size;
+        if (bytes < 1024)
+            return `${bytes} B`;
+        if (bytes < 1024 * 1024)
+            return `${(bytes / 1024).toFixed(2)} KB`;
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Format a file path for display (shorten if too long).
+ */
+export function formatFilePath(filePath, maxLength = 60) {
+    if (filePath.length <= maxLength)
+        return filePath;
+    // Try to show just the filename
+    const filename = path.basename(filePath);
+    if (filename.length <= maxLength)
+        return filename;
+    // Truncate filename
+    return `...${filename.slice(-(maxLength - 3))}`;
+}
+//# sourceMappingURL=json-file-saver.js.map

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

@@ -0,0 +1,63 @@
+/**
+ * JSON formatting utilities for displaying large JSON data efficiently.
+ * Provides tree view formatting and pagination for arrays.
+ */
+export interface JSONTreeOptions {
+    /** Maximum depth to expand by default */
+    maxDepth?: number;
+    /** Maximum items to show in arrays before pagination */
+    maxArrayItems?: number;
+    /** Items per page for pagination */
+    itemsPerPage?: number;
+    /** Current page for pagination (0-indexed) */
+    currentPage?: number;
+    /** Whether to show line numbers */
+    showLineNumbers?: boolean;
+    /** Indentation string */
+    indent?: string;
+}
+export interface JSONTreeNode {
+    key?: string;
+    value: unknown;
+    type: 'object' | 'array' | 'primitive';
+    expanded: boolean;
+    children?: JSONTreeNode[];
+    /** For arrays: total count and pagination info */
+    arrayInfo?: {
+        total: number;
+        start: number;
+        end: number;
+        currentPage: number;
+        totalPages: number;
+    };
+}
+/**
+ * Convert JSON value to tree structure with pagination support.
+ */
+export declare function jsonToTree(data: unknown, options?: JSONTreeOptions): JSONTreeNode;
+/**
+ * Format JSON tree as a string with tree structure.
+ */
+export declare function formatJSONTree(node: JSONTreeNode, options?: JSONTreeOptions): string;
+/**
+ * Format JSON with pagination for large arrays.
+ * Returns formatted string with pagination info.
+ */
+export declare function formatJSONWithPagination(data: unknown, options?: JSONTreeOptions): string;
+/**
+ * Get summary information about JSON structure.
+ * Optimized to avoid expensive stringification for large data.
+ */
+export declare function getJSONSummary(data: unknown): {
+    type: string;
+    size: number;
+    itemCount?: number;
+    keyCount?: number;
+    depth: number;
+    hasLargeArrays: boolean;
+};
+/**
+ * Estimate object size without full stringification (much faster for large objects).
+ */
+export declare function estimateObjectSize(obj: unknown): number;
+//# sourceMappingURL=json-formatter.d.ts.map

package/dist/utils/json-formatter.js

@@ -0,0 +1,344 @@
+/**
+ * JSON formatting utilities for displaying large JSON data efficiently.
+ * Provides tree view formatting and pagination for arrays.
+ */
+/**
+ * Convert JSON value to tree structure with pagination support.
+ */
+export function jsonToTree(data, options = {}) {
+    const { maxDepth = 3, maxArrayItems = 50, itemsPerPage = 20, currentPage = 0, } = options;
+    function buildNode(value, depth, key) {
+        if (value === null) {
+            return {
+                key,
+                value: null,
+                type: 'primitive',
+                expanded: depth < maxDepth,
+            };
+        }
+        if (Array.isArray(value)) {
+            const total = value.length;
+            const totalPages = Math.ceil(total / itemsPerPage);
+            const start = currentPage * itemsPerPage;
+            const end = Math.min(start + itemsPerPage, total);
+            const paginatedItems = value.slice(start, end);
+            return {
+                key,
+                value: paginatedItems,
+                type: 'array',
+                expanded: depth < maxDepth && total <= maxArrayItems,
+                arrayInfo: {
+                    total,
+                    start: start + 1, // 1-indexed for display
+                    end,
+                    currentPage,
+                    totalPages,
+                },
+                children: depth < maxDepth && total <= maxArrayItems
+                    ? paginatedItems.map((item, idx) => buildNode(item, depth + 1, `[${start + idx}]`))
+                    : undefined,
+            };
+        }
+        if (typeof value === 'object' && value !== null) {
+            const obj = value;
+            const keys = Object.keys(obj);
+            const expanded = depth < maxDepth;
+            return {
+                key,
+                value: obj,
+                type: 'object',
+                expanded,
+                children: expanded
+                    ? keys.map(k => buildNode(obj[k], depth + 1, k))
+                    : undefined,
+            };
+        }
+        // Primitive value
+        return {
+            key,
+            value,
+            type: 'primitive',
+            expanded: true,
+        };
+    }
+    return buildNode(data, 0);
+}
+/**
+ * Format JSON tree as a string with tree structure.
+ */
+export function formatJSONTree(node, options = {}) {
+    const { showLineNumbers = false } = options;
+    const lines = [];
+    let lineNumber = 1;
+    function formatNode(node, prefix, isLast, depth) {
+        const connector = isLast ? '└─' : '├─';
+        const nextPrefix = isLast ? '   ' : '│  ';
+        // Format key
+        if (node.key !== undefined) {
+            const keyPart = `${prefix}${connector} ${node.key}: `;
+            const lineNum = showLineNumbers ? `${lineNumber++}. `.padStart(6) : '';
+            lines.push(`${lineNum}${keyPart}`);
+        }
+        // Format value based on type
+        if (node.type === 'primitive') {
+            const valueStr = formatPrimitive(node.value);
+            const lastLine = lines[lines.length - 1] || '';
+            if (lastLine.includes(':')) {
+                lines[lines.length - 1] = lastLine + valueStr;
+            }
+            else {
+                lines.push(`${prefix}${connector} ${valueStr}`);
+            }
+        }
+        else if (node.type === 'array') {
+            const arrayInfo = node.arrayInfo;
+            if (arrayInfo && arrayInfo.total > arrayInfo.end - arrayInfo.start + 1) {
+                // Paginated array
+                const info = `[Array: ${arrayInfo.total} items, showing ${arrayInfo.start}-${arrayInfo.end} (page ${arrayInfo.currentPage + 1}/${arrayInfo.totalPages})]`;
+                const lastLine = lines[lines.length - 1] || '';
+                if (lastLine.includes(':')) {
+                    lines[lines.length - 1] = lastLine + info;
+                }
+                else {
+                    lines.push(`${prefix}${connector} ${info}`);
+                }
+            }
+            else {
+                const lastLine = lines[lines.length - 1] || '';
+                if (lastLine.includes(':')) {
+                    lines[lines.length - 1] =
+                        lastLine + `[Array: ${arrayInfo?.total || 0} items]`;
+                }
+            }
+            if (node.expanded && node.children) {
+                node.children.forEach((child, idx) => {
+                    const isLastChild = idx === node.children.length - 1;
+                    formatNode(child, prefix + (node.key !== undefined ? nextPrefix : ''), isLastChild, depth + 1);
+                });
+            }
+            else if (!node.expanded && arrayInfo) {
+                lines.push(`${prefix}${nextPrefix}... (${arrayInfo.total} items, use /expand to view)`);
+            }
+        }
+        else if (node.type === 'object') {
+            const obj = node.value;
+            const keyCount = Object.keys(obj).length;
+            const lastLine = lines[lines.length - 1] || '';
+            if (lastLine.includes(':')) {
+                lines[lines.length - 1] = lastLine + `{Object: ${keyCount} keys}`;
+            }
+            if (node.expanded && node.children) {
+                node.children.forEach((child, idx) => {
+                    const isLastChild = idx === node.children.length - 1;
+                    formatNode(child, prefix + (node.key !== undefined ? nextPrefix : ''), isLastChild, depth + 1);
+                });
+            }
+            else if (!node.expanded) {
+                lines.push(`${prefix}${nextPrefix}... (${keyCount} keys, use /expand to view)`);
+            }
+        }
+    }
+    formatNode(node, '', true, 0);
+    return lines.join('\n');
+}
+/**
+ * Format primitive value for display.
+ */
+function formatPrimitive(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string') {
+        // Truncate long strings
+        if (value.length > 100) {
+            return `"${value.substring(0, 97)}..." (${value.length} chars)`;
+        }
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    if (typeof value === 'undefined')
+        return 'undefined';
+    if (typeof value === 'function')
+        return '[Function]';
+    if (typeof value === 'symbol')
+        return value.toString();
+    if (typeof value === 'object' && value !== null) {
+        // For objects, show a summary instead of stringifying
+        return '[Object]';
+    }
+    // Fallback for any other types
+    return '[Unknown]';
+}
+/**
+ * Format JSON with pagination for large arrays.
+ * Returns formatted string with pagination info.
+ */
+export function formatJSONWithPagination(data, options = {}) {
+    const tree = jsonToTree(data, options);
+    return formatJSONTree(tree, options);
+}
+/**
+ * Get summary information about JSON structure.
+ * Optimized to avoid expensive stringification for large data.
+ */
+export function getJSONSummary(data) {
+    // Fast size estimation without full stringification for large data
+    let size;
+    try {
+        // For small data, use actual stringification
+        // For large data, estimate to avoid blocking
+        if (typeof data === 'string') {
+            size = Buffer.byteLength(data, 'utf8');
+        }
+        else {
+            // Quick check: if it's a large array/object, estimate instead
+            const isLarge = (Array.isArray(data) && data.length > 1000) ||
+                (typeof data === 'object' &&
+                    data !== null &&
+                    !Array.isArray(data) &&
+                    Object.keys(data).length > 100);
+            if (isLarge) {
+                // Estimate size without full stringification
+                // Create a small sample by taking a slice/portion of the data
+                let sample;
+                if (Array.isArray(data)) {
+                    // Sample first 10 items
+                    sample = data.slice(0, 10);
+                }
+                else {
+                    // Sample first 10 keys
+                    const keys = Object.keys(data).slice(0, 10);
+                    sample = Object.fromEntries(keys.map(key => [key, data[key]]));
+                }
+                const sampleString = JSON.stringify(sample);
+                const estimatedSizePerChar = Buffer.byteLength(sampleString, 'utf8') / sampleString.length;
+                const estimatedChars = estimateObjectSize(data);
+                size = Math.floor(estimatedChars * estimatedSizePerChar);
+            }
+            else {
+                // Small data: use actual stringification
+                const jsonString = JSON.stringify(data);
+                size = Buffer.byteLength(jsonString, 'utf8');
+            }
+        }
+    }
+    catch {
+        // Fallback: estimate
+        size = estimateObjectSize(data) * 2; // Rough estimate
+    }
+    function analyze(value, depth) {
+        if (value === null || typeof value !== 'object') {
+            return {
+                maxDepth: depth,
+                itemCount: 0,
+                keyCount: 0,
+                hasLargeArrays: false,
+            };
+        }
+        if (Array.isArray(value)) {
+            const itemCount = value.length;
+            let maxDepth = depth;
+            let totalKeys = 0;
+            let hasLargeArrays = itemCount > 100;
+            for (const item of value.slice(0, 10)) {
+                // Sample first 10 items
+                const result = analyze(item, depth + 1);
+                maxDepth = Math.max(maxDepth, result.maxDepth);
+                totalKeys += result.keyCount;
+                hasLargeArrays = hasLargeArrays || result.hasLargeArrays;
+            }
+            return {
+                maxDepth,
+                itemCount,
+                keyCount: totalKeys,
+                hasLargeArrays,
+            };
+        }
+        const obj = value;
+        const keys = Object.keys(obj);
+        let maxDepth = depth;
+        let totalItems = 0;
+        let totalKeys = keys.length;
+        let hasLargeArrays = false;
+        for (const key of keys) {
+            const result = analyze(obj[key], depth + 1);
+            maxDepth = Math.max(maxDepth, result.maxDepth);
+            totalItems += result.itemCount;
+            totalKeys += result.keyCount;
+            hasLargeArrays = hasLargeArrays || result.hasLargeArrays;
+        }
+        return {
+            maxDepth,
+            itemCount: totalItems,
+            keyCount: totalKeys,
+            hasLargeArrays,
+        };
+    }
+    const analysis = analyze(data, 0);
+    const type = Array.isArray(data)
+        ? 'array'
+        : typeof data === 'object' && data !== null
+            ? 'object'
+            : typeof data;
+    return {
+        type,
+        size,
+        itemCount: Array.isArray(data) ? data.length : analysis.itemCount,
+        keyCount: typeof data === 'object' && data !== null && !Array.isArray(data)
+            ? Object.keys(data).length
+            : undefined,
+        depth: analysis.maxDepth,
+        hasLargeArrays: analysis.hasLargeArrays || (Array.isArray(data) && data.length > 100),
+    };
+}
+/**
+ * Estimate object size without full stringification (much faster for large objects).
+ */
+export function estimateObjectSize(obj) {
+    if (obj === null || obj === undefined)
+        return 4; // "null"
+    if (typeof obj === 'string')
+        return obj.length + 2; // quotes
+    if (typeof obj === 'number')
+        return 10; // average number length
+    if (typeof obj === 'boolean')
+        return 5; // "true"/"false"
+    if (Array.isArray(obj)) {
+        // Estimate: brackets + commas + items
+        let size = 2; // brackets
+        for (let i = 0; i < Math.min(obj.length, 100); i++) {
+            // Sample first 100 items
+            size += estimateObjectSize(obj[i]) + 1; // +1 for comma
+        }
+        if (obj.length > 100) {
+            // Extrapolate for remaining items
+            const avgItemSize = size / Math.min(obj.length, 100);
+            size += (obj.length - 100) * avgItemSize;
+        }
+        return size;
+    }
+    if (typeof obj === 'object') {
+        const SAMPLE_LIMIT = 100;
+        const keys = Object.keys(obj);
+        const sampleCount = Math.min(keys.length, SAMPLE_LIMIT);
+        let accumulatedSize = 0;
+        // Sample first sampleCount keys
+        for (let i = 0; i < sampleCount; i++) {
+            const key = keys[i]; // Safe: i < sampleCount <= keys.length
+            accumulatedSize += key.length + 3; // key + quotes + colon
+            accumulatedSize +=
+                estimateObjectSize(obj[key]) + 1; // +1 for comma
+        }
+        // If all keys were sampled, return exact size
+        if (sampleCount === keys.length) {
+            return 2 + accumulatedSize; // +2 for braces
+        }
+        // Extrapolate for remaining keys
+        const extrapolatedSize = accumulatedSize * (keys.length / sampleCount);
+        return 2 + extrapolatedSize; // +2 for braces
+    }
+    return 10; // fallback estimate
+}
+//# sourceMappingURL=json-formatter.js.map

package/dist/utils/logger.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Unified logging utility for Syrin.
+ * Combines structured logging with styled console output.
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+export declare const Icon: {
+    readonly ERROR: "❌";
+    readonly WARNING: "⚠️";
+    readonly TIP: "💡";
+    readonly SUCCESS: "✓";
+    readonly FAILURE: "✗";
+    readonly CHECK: "✅";
+    readonly FOLDER: "📁";
+    readonly DOCUMENT: "📝";
+};
+export type IconType = (typeof Icon)[keyof typeof Icon];
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, unknown>;
+    error?: Error;
+}
+declare const colors: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly red: "\u001B[31m";
+    readonly cyan: "\u001B[36m";
+    readonly blue: "\u001B[34m";
+};
+type ColorKey = keyof typeof colors;
+/**
+ * Unified logger class with structured logging and styled output.
+ */
+export declare class Log {
+    private level;
+    private context;
+    private useStructuredLogging;
+    constructor(level?: LogLevel, context?: Record<string, unknown>, useStructuredLogging?: boolean);
+    /**
+     * Create a child logger with additional context.
+     */
+    child(additionalContext: Record<string, unknown>): Log;
+    /**
+     * Set the log level.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Enable or disable structured logging.
+     */
+    setStructuredLogging(enabled: boolean): void;
+    /**
+     * Style text with colors and formatting.
+     */
+    private style;
+    /**
+     * Internal structured logging method.
+     */
+    private structuredLog;
+    /**
+     * Print styled text to console.
+     */
+    private print;
+    /**
+     * Print a heading (green, bold).
+     */
+    heading(text: string): void;
+    /**
+     * Print a label (dim).
+     */
+    label(text: string): void;
+    /**
+     * Print a value (cyan).
+     */
+    value(text: string): void;
+    /**
+     * Log/print success message (green) with success icon.
+     * For structured logging: logs at INFO level
+     * For styled output: prints with green color and success icon
+     */
+    success(text: string, icon?: IconType): void;
+    /**
+     * Log/print error message (red) with error icon.
+     * For structured logging: logs at ERROR level (can include Error object)
+     * For styled output: prints with red color and error icon
+     */
+    error(message: string, errorOrIcon?: Error | IconType, contextOrIcon?: Record<string, unknown> | IconType): void;
+    /**
+     * Log/print warning message (yellow) with warning icon.
+     * For structured logging: logs at WARN level
+     * For styled output: prints with yellow color and warning icon
+     */
+    warning(text: string, context?: Record<string, unknown>): void;
+    warning(text: string, icon?: IconType): void;
+    /**
+     * Alias for warning() to match standard logging convention (warn).
+     * For structured logging: logs at WARN level
+     * For styled output: prints with yellow color and warning icon
+     */
+    warn(text: string, context?: Record<string, unknown>): void;
+    warn(text: string, icon?: IconType): void;
+    /**
+     * Log/print info message (cyan) with tip icon.
+     * For structured logging: logs at INFO level
+     * For styled output: prints with cyan color and tip icon
+     */
+    info(text: string, context?: Record<string, unknown>): void;
+    info(text: string, icon?: IconType): void;
+    /**
+     * Log/print debug message (dim).
+     * For structured logging: logs at DEBUG level
+     * For styled output: prints with dim color
+     */
+    debug(text: string, context?: Record<string, unknown>): void;
+    debug(text: string, icon?: IconType): void;
+    /**
+     * Print a line with label and value.
+     */
+    labelValue(labelText: string, valueText: string): void;
+    /**
+     * Print a numbered item.
+     */
+    numberedItem(number: number, text: string, ...additionalStyles: ColorKey[]): void;
+    /**
+     * Print a checkmark with text.
+     */
+    checkmark(text: string): void;
+    /**
+     * Print an X mark with text.
+     */
+    xmark(text: string): void;
+    /**
+     * Get a styled tick/checkmark (✓) in green.
+     * Returns a styled string that can be used in other messages.
+     */
+    tick(): string;
+    /**
+     * Get a styled cross/X mark (✗) in red.
+     * Returns a styled string that can be used in other messages.
+     */
+    cross(): string;
+    /**
+     * Print a warning symbol with text.
+     */
+    warnSymbol(text: string): void;
+    /**
+     * Print plain text (no styling).
+     */
+    plain(text: string): void;
+    /**
+     * Print an empty line.
+     */
+    blank(): void;
+    /**
+     * Style text with colors and formatting (returns styled string).
+     * This is a public method that can be used to get styled strings without printing.
+     */
+    styleText(text: string, ...styles: ColorKey[]): string;
+}
+/**
+ * Default logger instance for styled output (non-structured).
+ * Use this for UI/presentation output.
+ */
+export declare const log: Log;
+/**
+ * Default structured logger instance.
+ * Use this for application logging with levels and context.
+ */
+export declare const logger: Log;
+/**
+ * Create a logger with a specific context.
+ */
+export declare function createLogger(context: Record<string, unknown>): Log;
+export {};
+//# sourceMappingURL=logger.d.ts.map