codedev-mcp 3.2.0

package/dist/utils/plugins.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Plugin architecture for codedev-mcp.
+ * Users extend the server with custom analyzers without forking.
+ *
+ * Plugin locations (in priority order):
+ *   1. ./.codedev-mcp/plugins/           (project-local)
+ *   2. ~/.codedev-mcp/plugins/           (user-global)
+ *   3. npm packages: codedev-plugin-*    (marketplace)
+ *
+ * Plugin format:
+ *   Each plugin is a directory with a plugin.json manifest and an index.js entry point.
+ *   npm marketplace plugins follow the same format but are installed via npm.
+ */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    description: string;
+    author?: string;
+    tools?: PluginToolDef[];
+    patterns?: PluginPatternDef[];
+    languages?: PluginLanguageDef[];
+}
+export interface PluginToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface PluginPatternDef {
+    name: string;
+    pattern: string;
+    severity: string;
+    description: string;
+    recommendation: string;
+}
+export interface PluginLanguageDef {
+    name: string;
+    extensions: string[];
+    commentSingle?: string;
+    commentMultiStart?: string;
+    commentMultiEnd?: string;
+    functionPatterns?: string[];
+    classPatterns?: string[];
+}
+export interface PluginModule {
+    tools?: Record<string, (params: Record<string, unknown>, context: {
+        cwd: string;
+    }) => Promise<string>>;
+}
+export interface LoadedPlugin {
+    manifest: PluginManifest;
+    pluginPath: string;
+    module?: PluginModule;
+}
+/**
+ * Discover and load plugins from standard locations + npm marketplace.
+ * @param cwd - The working directory to search for plugins.
+ * @returns An array of loaded plugins.
+ */
+export declare function loadPlugins(cwd: string): Promise<LoadedPlugin[]>;
+/**
+ * Get all custom patterns from loaded plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of pattern definitions from all plugins.
+ */
+export declare function getPluginPatterns(plugins: LoadedPlugin[]): PluginPatternDef[];
+/**
+ * Get all custom language definitions from plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of language definitions from all plugins.
+ */
+export declare function getPluginLanguages(plugins: LoadedPlugin[]): PluginLanguageDef[];
+/**
+ * Get all custom tool definitions from plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of tool definitions with their plugin names.
+ */
+export declare function getPluginTools(plugins: LoadedPlugin[]): {
+    plugin: string;
+    tool: PluginToolDef;
+}[];
+/**
+ * Execute a plugin tool handler.
+ * @param plugin - The loaded plugin to execute.
+ * @param toolName - The tool name to invoke.
+ * @param params - Parameters to pass to the tool.
+ * @param context - Execution context.
+ * @param context.cwd - The current working directory.
+ * @returns The string result from the tool handler.
+ */
+export declare function executePluginTool(plugin: LoadedPlugin, toolName: string, params: Record<string, unknown>, context: {
+    cwd: string;
+}): Promise<string>;
+/**
+ * Generate a plugin scaffold for users.
+ * Produces both plugin.json (native) and package.json (npm marketplace) formats.
+ * @param name - The plugin name.
+ * @returns An object containing manifest, packageJson, indexJs, and readme strings.
+ */
+export declare function generatePluginScaffold(name: string): {
+    manifest: string;
+    packageJson: string;
+    indexJs: string;
+    readme: string;
+};
+//# sourceMappingURL=plugins.d.ts.map

package/dist/utils/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/utils/plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;CACxG;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAwDtE;AAqHD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,iBAAiB,EAAE,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,EAAE,CAEjG;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACvB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CA0GA"}

package/dist/utils/plugins.js

@@ -0,0 +1,325 @@
+/**
+ * Plugin architecture for codedev-mcp.
+ * Users extend the server with custom analyzers without forking.
+ *
+ * Plugin locations (in priority order):
+ *   1. ./.codedev-mcp/plugins/           (project-local)
+ *   2. ~/.codedev-mcp/plugins/           (user-global)
+ *   3. npm packages: codedev-plugin-*    (marketplace)
+ *
+ * Plugin format:
+ *   Each plugin is a directory with a plugin.json manifest and an index.js entry point.
+ *   npm marketplace plugins follow the same format but are installed via npm.
+ */
+import { readFile, readdir, access } from 'node:fs/promises';
+import path from 'node:path';
+import { logger } from './logger.js';
+/**
+ * Discover and load plugins from standard locations + npm marketplace.
+ * @param cwd - The working directory to search for plugins.
+ * @returns An array of loaded plugins.
+ */
+export async function loadPlugins(cwd) {
+    const plugins = [];
+    // 1. Local and global plugin directories
+    const pluginDirs = [
+        path.join(cwd, '.codedev-mcp', 'plugins'),
+        path.join(process.env.HOME || '', '.codedev-mcp', 'plugins'),
+    ];
+    for (const dir of pluginDirs) {
+        try {
+            await access(dir);
+            const entries = await readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const pluginPath = path.join(dir, entry.name);
+                const manifestPath = path.join(pluginPath, 'plugin.json');
+                try {
+                    const manifestContent = await readFile(manifestPath, 'utf-8');
+                    const manifest = JSON.parse(manifestContent);
+                    // Validate manifest
+                    if (!manifest.name || !manifest.version) {
+                        logger.error(`Plugin ${entry.name}: Invalid manifest (missing name or version)`);
+                        continue;
+                    }
+                    // Try loading the module
+                    let module;
+                    const entryPoint = path.join(pluginPath, 'index.js');
+                    try {
+                        await access(entryPoint);
+                        const importedModule = await import(entryPoint);
+                        module = importedModule;
+                    }
+                    catch {
+                        // Plugin might not have code (pattern-only or language-only plugins)
+                    }
+                    plugins.push({ manifest, pluginPath, module });
+                }
+                catch {
+                    // Skip directories without valid plugin.json
+                }
+            }
+        }
+        catch {
+            // Plugin directory doesn't exist
+        }
+    }
+    // 2. npm marketplace: auto-discover codedev-plugin-* packages
+    const npmPlugins = await discoverNpmPlugins(cwd);
+    plugins.push(...npmPlugins);
+    return plugins;
+}
+/**
+ * Discover npm packages matching the `codedev-plugin-*` naming convention.
+ * Searches node_modules in the project and globally.
+ * @param cwd - The working directory.
+ * @returns An array of loaded npm plugins.
+ */
+async function discoverNpmPlugins(cwd) {
+    const plugins = [];
+    const PREFIX = 'codedev-plugin-';
+    const searchDirs = [
+        path.join(cwd, 'node_modules'),
+        path.join(process.env.HOME || '', '.codedev-mcp', 'node_modules'),
+    ];
+    // Also check global node_modules
+    const globalPrefix = process.env.npm_config_prefix || '/usr/local';
+    searchDirs.push(path.join(globalPrefix, 'lib', 'node_modules'));
+    for (const nodeModulesDir of searchDirs) {
+        try {
+            await access(nodeModulesDir);
+            const entries = await readdir(nodeModulesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                // Match codedev-plugin-* or @scope/codedev-plugin-*
+                if (entry.isDirectory() && entry.name.startsWith(PREFIX)) {
+                    const plugin = await loadNpmPlugin(path.join(nodeModulesDir, entry.name));
+                    if (plugin)
+                        plugins.push(plugin);
+                }
+                // Check scoped packages (@scope/codedev-plugin-*)
+                if (entry.isDirectory() && entry.name.startsWith('@')) {
+                    try {
+                        const scopedEntries = await readdir(path.join(nodeModulesDir, entry.name), { withFileTypes: true });
+                        for (const scopedEntry of scopedEntries) {
+                            if (scopedEntry.isDirectory() && scopedEntry.name.startsWith(PREFIX)) {
+                                const plugin = await loadNpmPlugin(path.join(nodeModulesDir, entry.name, scopedEntry.name));
+                                if (plugin)
+                                    plugins.push(plugin);
+                            }
+                        }
+                    }
+                    catch {
+                        /* skip */
+                    }
+                }
+            }
+        }
+        catch {
+            /* node_modules doesn't exist */
+        }
+    }
+    return plugins;
+}
+/**
+ * Load a single npm marketplace plugin from its package directory.
+ * @param pkgDir - The package directory path.
+ * @returns The loaded plugin or null if loading failed.
+ */
+async function loadNpmPlugin(pkgDir) {
+    try {
+        // Try plugin.json first (codedev-mcp native format)
+        const manifestPath = path.join(pkgDir, 'plugin.json');
+        let manifest;
+        try {
+            const content = await readFile(manifestPath, 'utf-8');
+            manifest = JSON.parse(content);
+        }
+        catch {
+            // Fallback: read package.json and extract codedev config
+            const pkgJsonPath = path.join(pkgDir, 'package.json');
+            const pkgContent = await readFile(pkgJsonPath, 'utf-8');
+            const pkgJson = JSON.parse(pkgContent);
+            // Plugin must have a "codedev" key in package.json
+            const codedevConfig = pkgJson.codedev;
+            if (!codedevConfig)
+                return null;
+            manifest = {
+                name: pkgJson.name,
+                version: pkgJson.version,
+                description: pkgJson.description || '',
+                author: pkgJson.author,
+                tools: codedevConfig.tools,
+                patterns: codedevConfig.patterns,
+                languages: codedevConfig.languages,
+            };
+        }
+        if (!manifest.name || !manifest.version)
+            return null;
+        // Try loading the module
+        let module;
+        try {
+            const entryPoint = path.join(pkgDir, 'index.js');
+            await access(entryPoint);
+            module = (await import(entryPoint));
+        }
+        catch {
+            // Try package.json main field
+            try {
+                const pkgContent = await readFile(path.join(pkgDir, 'package.json'), 'utf-8');
+                const pkgJson = JSON.parse(pkgContent);
+                if (pkgJson.main) {
+                    module = (await import(path.join(pkgDir, pkgJson.main)));
+                }
+            }
+            catch {
+                /* no module */
+            }
+        }
+        return { manifest, pluginPath: pkgDir, module };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get all custom patterns from loaded plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of pattern definitions from all plugins.
+ */
+export function getPluginPatterns(plugins) {
+    return plugins.flatMap((p) => p.manifest.patterns || []);
+}
+/**
+ * Get all custom language definitions from plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of language definitions from all plugins.
+ */
+export function getPluginLanguages(plugins) {
+    return plugins.flatMap((p) => p.manifest.languages || []);
+}
+/**
+ * Get all custom tool definitions from plugins.
+ * @param plugins - The loaded plugins.
+ * @returns An array of tool definitions with their plugin names.
+ */
+export function getPluginTools(plugins) {
+    return plugins.flatMap((p) => (p.manifest.tools || []).map((t) => ({ plugin: p.manifest.name, tool: t })));
+}
+/**
+ * Execute a plugin tool handler.
+ * @param plugin - The loaded plugin to execute.
+ * @param toolName - The tool name to invoke.
+ * @param params - Parameters to pass to the tool.
+ * @param context - Execution context.
+ * @param context.cwd - The current working directory.
+ * @returns The string result from the tool handler.
+ */
+export async function executePluginTool(plugin, toolName, params, context) {
+    if (!plugin.module?.tools?.[toolName]) {
+        throw new Error(`Tool "${toolName}" not found in plugin "${plugin.manifest.name}"`);
+    }
+    return plugin.module.tools[toolName](params, context);
+}
+/**
+ * Generate a plugin scaffold for users.
+ * Produces both plugin.json (native) and package.json (npm marketplace) formats.
+ * @param name - The plugin name.
+ * @returns An object containing manifest, packageJson, indexJs, and readme strings.
+ */
+export function generatePluginScaffold(name) {
+    const manifest = JSON.stringify({
+        name,
+        version: '1.0.0',
+        description: `Custom codedev-mcp plugin: ${name}`,
+        tools: [
+            {
+                name: `${name}_analyze`,
+                description: `Run ${name} analysis`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'File or directory to analyze' },
+                    },
+                },
+            },
+        ],
+        patterns: [
+            {
+                name: `${name}_check`,
+                pattern: 'TODO',
+                severity: 'info',
+                description: `Custom ${name} pattern check`,
+                recommendation: 'Review and address this pattern.',
+            },
+        ],
+    }, null, 2);
+    const packageJson = JSON.stringify({
+        name: `codedev-plugin-${name}`,
+        version: '1.0.0',
+        description: `codedev-mcp marketplace plugin: ${name}`,
+        main: 'index.js',
+        keywords: ['codedev-mcp', 'mcp', 'code-analysis', 'plugin'],
+        codedev: {
+            tools: [
+                {
+                    name: `${name}_analyze`,
+                    description: `Run ${name} analysis`,
+                    inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+                },
+            ],
+            patterns: [
+                {
+                    name: `${name}_check`,
+                    pattern: 'TODO',
+                    severity: 'info',
+                    description: `Custom ${name} pattern check`,
+                    recommendation: 'Review and address this pattern.',
+                },
+            ],
+        },
+    }, null, 2);
+    const indexJs = `
+// ${name} plugin for codedev-mcp
+// Exports tool handlers that the server will call
+
+export const tools = {
+  async ${name}_analyze(params, context) {
+    const { cwd } = context;
+    const targetPath = params.path || cwd;
+
+    // Your custom analysis logic here
+    return \`${name} analysis complete for \${targetPath}\`;
+  },
+};
+`.trim();
+    const readme = `# codedev-plugin-${name}
+
+Custom plugin for codedev-mcp.
+
+## Installation
+
+### npm marketplace (recommended)
+\`\`\`bash
+npm install -g codedev-plugin-${name}
+\`\`\`
+
+### Manual
+1. Copy this folder to \`~/.codedev-mcp/plugins/${name}/\`
+2. Restart codedev-mcp
+
+## Tools
+- \`${name}_analyze\`: Run custom analysis
+
+## Patterns
+- \`${name}_check\`: Custom pattern detection
+
+## Publishing
+\`\`\`bash
+npm publish
+\`\`\`
+The \`codedev-plugin-\` prefix is automatically discovered by codedev-mcp.
+`;
+    return { manifest, packageJson, indexJs, readme };
+}
+//# sourceMappingURL=plugins.js.map

package/dist/utils/plugins.js.map

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

package/dist/utils/security.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Validate that a path is safe to access within permissible roots.
+ * Throws strict errors for violations.
+ *
+ * @param userPath - The input path from the user/agent (relative or absolute)
+ * @param allowedRoots - Array of absolute paths permissible for access
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns The normalized, validated absolute path.
+ */
+export declare function validatePath(userPath: string, allowedRoots: string[], cwd: string): string;
+/**
+ * Sanitize input to reject suspicious patterns immediately.
+ * @param input - The input string to sanitize.
+ * @returns The sanitized input string.
+ */
+export declare function sanitizeInput(input: string): string;
+//# sourceMappingURL=security.d.ts.map

package/dist/utils/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/utils/security.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAkC1F;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnD"}

package/dist/utils/security.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+/**
+ * Validate that a path is safe to access within permissible roots.
+ * Throws strict errors for violations.
+ *
+ * @param userPath - The input path from the user/agent (relative or absolute)
+ * @param allowedRoots - Array of absolute paths permissible for access
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns The normalized, validated absolute path.
+ */
+export function validatePath(userPath, allowedRoots, cwd) {
+    // 1. Basic Input Validation
+    if (userPath.includes('\0')) {
+        throw new Error('Security Blocked: Path contains null bytes.');
+    }
+    // 2. Resolve absolute path
+    const resolved = path.resolve(cwd, userPath);
+    // 3. Normalize (resolves .. segments)
+    const normalized = path.normalize(resolved);
+    // 4. Verify containment
+    // Check if the path starts with any of the allowed roots
+    // Must compare with trailing separator to prevent /var/lib vs /var/lib-private partial matches
+    // Exception: if the path IS the root itself.
+    const isAllowed = allowedRoots.some((root) => {
+        const relative = path.relative(root, normalized);
+        // blocked: relative starts with '..' (outside root)
+        // blocked: absolute path (different drive on windows, or just outside)
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return false;
+        }
+        return true;
+    });
+    if (!isAllowed) {
+        throw new Error(`Security Blocked: Path "${userPath}" resolves to "${normalized}", which is outside allowed roots: [${allowedRoots.join(', ')}]`);
+    }
+    return normalized;
+}
+/**
+ * Sanitize input to reject suspicious patterns immediately.
+ * @param input - The input string to sanitize.
+ * @returns The sanitized input string.
+ */
+export function sanitizeInput(input) {
+    if (input.includes('\0'))
+        throw new Error('Input contains null bytes');
+    return input;
+}
+//# sourceMappingURL=security.js.map

package/dist/utils/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../src/utils/security.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,YAAsB,EAAE,GAAW;IAChF,4BAA4B;IAC5B,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,2BAA2B;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAE7C,sCAAsC;IACtC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAE5C,wBAAwB;IACxB,yDAAyD;IACzD,+FAA+F;IAC/F,6CAA6C;IAC7C,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAEjD,oDAAoD;QACpD,uEAAuE;QACvE,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,2BAA2B,QAAQ,kBAAkB,UAAU,uCAAuC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACjI,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACvE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/streaming.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Streaming Utilities
+ * Provides streaming support for large results
+ */
+export interface StreamOptions {
+    chunkSize?: number;
+    delayMs?: number;
+    onProgress?: (progress: number, total: number) => void;
+}
+/**
+ * Stream large text content in chunks
+ * @param content - The text content to stream.
+ * @param options - Streaming options (chunkSize, delayMs, onProgress).
+ * @returns An async generator yielding string chunks.
+ */
+export declare function streamContent(content: string, options?: StreamOptions): AsyncGenerator<string, void, unknown>;
+/**
+ * Stream array results in batches
+ * @param items - The array of items to stream.
+ * @param options - Streaming options (chunkSize, delayMs, onProgress).
+ * @returns An async generator yielding batches of items.
+ */
+export declare function streamArray<T>(items: T[], options?: StreamOptions): AsyncGenerator<T[], void, unknown>;
+/**
+ * Format streaming response with progress
+ * @param chunks - The chunks to format.
+ * @param metadata - Metadata with total and processed counts.
+ * @param metadata.total - Total number of items.
+ * @param metadata.processed - Number of items processed.
+ * @returns A formatted string with progress indicator.
+ */
+export declare function formatStreamingResponse(chunks: string[], metadata: {
+    total: number;
+    processed: number;
+}): string;
+/**
+ * Wrap a long-running operation with timeout
+ * @param operation - The promise to wrap with a timeout.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param operationName - A name for the operation (used in error messages).
+ * @returns The result of the operation.
+ */
+export declare function withTimeout<T>(operation: Promise<T>, timeoutMs: number, operationName?: string): Promise<T>;
+/**
+ * Truncate large results with summary
+ * @param items - The array of items to truncate.
+ * @param maxItems - Maximum number of items to keep.
+ * @returns An object with truncated items and metadata.
+ */
+export declare function truncateResults<T>(items: T[], maxItems: number): {
+    items: T[];
+    truncated: boolean;
+    total: number;
+    shown: number;
+};
+//# sourceMappingURL=streaming.d.ts.map

package/dist/utils/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/utils/streaming.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxD;AAED;;;;;GAKG;AACH,wBAAuB,aAAa,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAgBvC;AAED;;;;;GAKG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAgBjH;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGhH;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EACrB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAoB,GAClC,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAUlE"}