glancey 2.0.0

package/dist/tools/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Common types for MCP tool handlers.
+ */
+import type { CodeIndexer } from '../search/indexer.js';
+/**
+ * Standard MCP tool response format.
+ */
+export interface ToolResponse {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    /** Indicates an error response */
+    isError?: boolean;
+}
+/**
+ * Context passed to all tool handlers.
+ */
+export interface ToolContext {
+    indexer: CodeIndexer;
+    projectPath: string;
+    toolGuidance: string;
+}
+/**
+ * Generic tool handler function signature.
+ */
+export type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs, context: ToolContext) => Promise<ToolResponse>;
+/**
+ * Helper to create a successful tool response.
+ */
+export declare function createToolResponse(text: string, guidance?: string): ToolResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACzD,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,WAAW,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3B;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,GAAG,YAAY,CASpF"}

package/dist/tools/types.js

@@ -0,0 +1,17 @@
+/**
+ * Common types for MCP tool handlers.
+ */
+/**
+ * Helper to create a successful tool response.
+ */
+export function createToolResponse(text, guidance = '') {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: text + guidance,
+            },
+        ],
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiCH;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,WAAmB,EAAE;IACpE,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,GAAG,QAAQ;aACtB;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/worktree-handlers.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tool handlers for worktree operations.
+ */
+import { type WorktreeInfo, type CreateWorktreeResult, type RemoveWorktreeResult, type ListWorktreesResult } from '../worktree/index.js';
+import type { ToolResponse } from './types.js';
+/**
+ * Interface for worktree manager operations (for testability).
+ */
+export interface IWorktreeManager {
+    createWorktree(options: {
+        shortName: string;
+        issueId?: string;
+        prefix?: 'feature' | 'fix' | 'refactor' | 'docs' | 'test';
+        baseBranch?: string;
+        installDeps?: boolean;
+        packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
+    }): Promise<CreateWorktreeResult>;
+    listWorktrees(): Promise<ListWorktreesResult>;
+    removeWorktree(options: {
+        name: string;
+        deleteBranch?: boolean;
+        force?: boolean;
+    }): Promise<RemoveWorktreeResult>;
+    getWorktreeInfo(name: string): Promise<WorktreeInfo | null>;
+}
+/**
+ * Context for worktree tools.
+ */
+export interface WorktreeToolContext {
+    projectPath: string;
+    toolGuidance: string;
+    /** Optional worktree manager instance (for testing). */
+    worktreeManager?: IWorktreeManager;
+}
+/**
+ * Arguments for create_worktree tool.
+ */
+export interface CreateWorktreeArgs {
+    shortName: string;
+    issueId?: string;
+    prefix?: 'feature' | 'fix' | 'refactor' | 'docs' | 'test';
+    baseBranch?: string;
+    installDeps?: boolean;
+    packageManager?: 'npm' | 'yarn' | 'pnpm' | 'bun';
+}
+/**
+ * Parse and validate create_worktree arguments.
+ */
+export declare function parseCreateWorktreeArgs(args: Record<string, unknown> | undefined): CreateWorktreeArgs;
+/**
+ * Format worktree creation result.
+ */
+export declare function formatWorktreeCreationResult(result: CreateWorktreeResult): string;
+/**
+ * Handle create_worktree tool.
+ */
+export declare function handleCreateWorktree(args: CreateWorktreeArgs, context: WorktreeToolContext): Promise<ToolResponse>;
+/**
+ * Handle list_worktrees tool.
+ */
+export declare function handleListWorktrees(context: WorktreeToolContext): Promise<ToolResponse>;
+/**
+ * Arguments for remove_worktree tool.
+ */
+export interface RemoveWorktreeArgs {
+    name: string;
+    deleteBranch?: boolean;
+    force?: boolean;
+}
+/**
+ * Parse and validate remove_worktree arguments.
+ */
+export declare function parseRemoveWorktreeArgs(args: Record<string, unknown> | undefined): RemoveWorktreeArgs;
+/**
+ * Format worktree removal result.
+ */
+export declare function formatWorktreeRemovalResult(name: string, result: RemoveWorktreeResult): string;
+/**
+ * Handle remove_worktree tool.
+ */
+export declare function handleRemoveWorktree(args: RemoveWorktreeArgs, context: WorktreeToolContext): Promise<ToolResponse>;
+/**
+ * Arguments for worktree_status tool.
+ */
+export interface WorktreeStatusArgs {
+    name: string;
+}
+/**
+ * Parse and validate worktree_status arguments.
+ */
+export declare function parseWorktreeStatusArgs(args: Record<string, unknown> | undefined): WorktreeStatusArgs;
+/**
+ * Handle worktree_status tool.
+ */
+export declare function handleWorktreeStatus(args: WorktreeStatusArgs, context: WorktreeToolContext): Promise<ToolResponse>;
+//# sourceMappingURL=worktree-handlers.d.ts.map

package/dist/tools/worktree-handlers.d.ts.map

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

package/dist/tools/worktree-handlers.js

@@ -0,0 +1,186 @@
+/**
+ * Tool handlers for worktree operations.
+ */
+import { WorktreeManager, formatWorktreeInfo, formatWorktreeList, } from '../worktree/index.js';
+import { createToolResponse } from './types.js';
+import { isString, isBoolean } from '../utils/type-guards.js';
+import { GlanceyError } from '../utils/errors.js';
+/**
+ * Get or create a worktree manager instance.
+ */
+function getWorktreeManager(context) {
+    return context.worktreeManager ?? new WorktreeManager(context.projectPath);
+}
+/**
+ * Parse and validate create_worktree arguments.
+ */
+export function parseCreateWorktreeArgs(args) {
+    const shortName = isString(args?.short_name) ? args.short_name : '';
+    if (!shortName) {
+        throw new GlanceyError('short_name is required', 'validation', {
+            tool: 'create_worktree',
+        });
+    }
+    const prefix = isString(args?.prefix) ? args.prefix : undefined;
+    const validPrefixes = ['feature', 'fix', 'refactor', 'docs', 'test'];
+    if (prefix && !validPrefixes.includes(prefix)) {
+        throw new GlanceyError(`prefix must be one of: ${validPrefixes.join(', ')}`, 'validation', {
+            tool: 'create_worktree',
+        });
+    }
+    const packageManager = isString(args?.package_manager) ? args.package_manager : undefined;
+    const validPackageManagers = ['npm', 'yarn', 'pnpm', 'bun'];
+    if (packageManager && !validPackageManagers.includes(packageManager)) {
+        throw new GlanceyError(`package_manager must be one of: ${validPackageManagers.join(', ')}`, 'validation', { tool: 'create_worktree' });
+    }
+    return {
+        shortName,
+        issueId: isString(args?.issue_id) ? args.issue_id : undefined,
+        prefix: prefix,
+        baseBranch: isString(args?.base_branch) ? args.base_branch : undefined,
+        installDeps: isBoolean(args?.install_deps) ? args.install_deps : true,
+        packageManager: packageManager,
+    };
+}
+/**
+ * Format worktree creation result.
+ */
+export function formatWorktreeCreationResult(result) {
+    if (!result.success) {
+        return `Failed to create worktree: ${result.error}`;
+    }
+    const worktree = result.worktree;
+    const parts = [];
+    parts.push('## Worktree Created\n');
+    parts.push(`**Name:** ${worktree?.name}`);
+    parts.push(`**Path:** ${worktree?.path}`);
+    parts.push(`**Branch:** ${worktree?.branch}`);
+    if (result.depsInstalled !== undefined) {
+        const depsStatus = result.depsInstalled ? 'installed' : 'skipped/failed';
+        const timeInfo = result.depsInstallTime ? ` (${result.depsInstallTime}ms)` : '';
+        parts.push(`**Dependencies:** ${depsStatus}${timeInfo}`);
+    }
+    parts.push('\n**Usage:** Spawn agent with `cwd: "' + (worktree?.path ?? '') + '"`');
+    return parts.join('\n');
+}
+/**
+ * Handle create_worktree tool.
+ */
+export async function handleCreateWorktree(args, context) {
+    const worktreeManager = getWorktreeManager(context);
+    const result = await worktreeManager.createWorktree({
+        shortName: args.shortName,
+        issueId: args.issueId,
+        prefix: args.prefix,
+        baseBranch: args.baseBranch,
+        installDeps: args.installDeps,
+        packageManager: args.packageManager,
+    });
+    if (!result.success) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to create worktree: ${result.error}` + context.toolGuidance,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return createToolResponse(formatWorktreeCreationResult(result), context.toolGuidance);
+}
+/**
+ * Handle list_worktrees tool.
+ */
+export async function handleListWorktrees(context) {
+    const worktreeManager = getWorktreeManager(context);
+    const result = await worktreeManager.listWorktrees();
+    return createToolResponse(formatWorktreeList(result), context.toolGuidance);
+}
+/**
+ * Parse and validate remove_worktree arguments.
+ */
+export function parseRemoveWorktreeArgs(args) {
+    const name = isString(args?.name) ? args.name : '';
+    if (!name) {
+        throw new GlanceyError('name is required', 'validation', {
+            tool: 'remove_worktree',
+        });
+    }
+    return {
+        name,
+        deleteBranch: isBoolean(args?.delete_branch) ? args.delete_branch : false,
+        force: isBoolean(args?.force) ? args.force : false,
+    };
+}
+/**
+ * Format worktree removal result.
+ */
+export function formatWorktreeRemovalResult(name, result) {
+    if (!result.success) {
+        return `Failed to remove worktree: ${result.error}`;
+    }
+    const parts = [];
+    parts.push('## Worktree Removed\n');
+    parts.push(`**Name:** ${name}`);
+    if (result.branch) {
+        parts.push(`**Branch:** ${result.branch}`);
+        parts.push(`**Branch deleted:** ${result.branchDeleted ? 'yes' : 'no'}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Handle remove_worktree tool.
+ */
+export async function handleRemoveWorktree(args, context) {
+    const worktreeManager = getWorktreeManager(context);
+    const result = await worktreeManager.removeWorktree({
+        name: args.name,
+        deleteBranch: args.deleteBranch,
+        force: args.force,
+    });
+    if (!result.success) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Failed to remove worktree: ${result.error}` + context.toolGuidance,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return createToolResponse(formatWorktreeRemovalResult(args.name, result), context.toolGuidance);
+}
+/**
+ * Parse and validate worktree_status arguments.
+ */
+export function parseWorktreeStatusArgs(args) {
+    const name = isString(args?.name) ? args.name : '';
+    if (!name) {
+        throw new GlanceyError('name is required', 'validation', {
+            tool: 'worktree_status',
+        });
+    }
+    return { name };
+}
+/**
+ * Handle worktree_status tool.
+ */
+export async function handleWorktreeStatus(args, context) {
+    const worktreeManager = getWorktreeManager(context);
+    const info = await worktreeManager.getWorktreeInfo(args.name);
+    if (!info) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Worktree "${args.name}" not found.` + context.toolGuidance,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return createToolResponse(formatWorktreeInfo(info), context.toolGuidance);
+}
+//# sourceMappingURL=worktree-handlers.js.map

package/dist/tools/worktree-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-handlers.js","sourceRoot":"","sources":["../../src/tools/worktree-handlers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GAKnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiClD;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAA4B;IACtD,OAAO,OAAO,CAAC,eAAe,IAAI,IAAI,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;AAC7E,CAAC;AAcD;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyC;IAEzC,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,YAAY,CAAC,wBAAwB,EAAE,YAAY,EAAE;YAC7D,IAAI,EAAE,iBAAiB;SACxB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACrE,IAAI,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,YAAY,CAAC,0BAA0B,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,EAAE;YACzF,IAAI,EAAE,iBAAiB;SACxB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5D,IAAI,cAAc,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,YAAY,CACpB,mCAAmC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACpE,YAAY,EACZ,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAC5B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS;QACT,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QAC7D,MAAM,EAAE,MAAsC;QAC9C,UAAU,EAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;QACtE,WAAW,EAAE,SAAS,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI;QACrE,cAAc,EAAE,cAAsD;KACvE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAA4B;IACvE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,8BAA8B,MAAM,CAAC,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,aAAa,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,aAAa,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,eAAe,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9C,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACzE,MAAM,QAAQ,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,eAAe,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,KAAK,CAAC,IAAI,CAAC,qBAAqB,UAAU,GAAG,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,uCAAuC,GAAG,CAAC,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAEpF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAwB,EACxB,OAA4B;IAE5B,MAAM,eAAe,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,cAAc,CAAC;QAClD,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,8BAA8B,MAAM,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,YAAY;iBAC1E;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,OAAO,kBAAkB,CAAC,4BAA4B,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;AACxF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAA4B;IACpE,MAAM,eAAe,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,aAAa,EAAE,CAAC;IACrD,OAAO,kBAAkB,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;AAC9E,CAAC;AAWD;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyC;IAEzC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,YAAY,EAAE;YACvD,IAAI,EAAE,iBAAiB;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,IAAI;QACJ,YAAY,EAAE,SAAS,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK;QACzE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK;KACnD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAY,EAAE,MAA4B;IACpF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,8BAA8B,MAAM,CAAC,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,KAAK,CAAC,IAAI,CAAC,uBAAuB,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAwB,EACxB,OAA4B;IAE5B,MAAM,eAAe,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,cAAc,CAAC;QAClD,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,8BAA8B,MAAM,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,YAAY;iBAC1E;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,OAAO,kBAAkB,CAAC,2BAA2B,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;AAClG,CAAC;AASD;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAyC;IAEzC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,YAAY,EAAE;YACvD,IAAI,EAAE,iBAAiB;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAwB,EACxB,OAA4B;IAE5B,MAAM,eAAe,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE9D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,aAAa,IAAI,CAAC,IAAI,cAAc,GAAG,OAAO,CAAC,YAAY;iBAClE;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,OAAO,kBAAkB,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;AAC5E,CAAC"}

package/dist/utils/cache.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Generic TTL-based LRU cache with configurable size and expiration.
+ * Provides a reusable caching utility for embeddings, metadata, and other data.
+ */
+export interface CacheOptions {
+    /** Maximum number of entries (default: 100) */
+    maxSize?: number;
+    /** Time-to-live in milliseconds (default: 1 hour) */
+    ttlMs?: number;
+}
+/**
+ * A generic LRU cache with TTL-based expiration.
+ *
+ * Features:
+ * - Configurable max size with LRU eviction
+ * - TTL-based expiration for entries
+ * - Automatic cleanup of expired entries on access
+ * - Thread-safe for single-threaded Node.js
+ *
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<number[]>({ maxSize: 50, ttlMs: 30000 });
+ * cache.set('key', [1, 2, 3]);
+ * const value = cache.get('key'); // [1, 2, 3] or undefined if expired
+ * ```
+ */
+export declare class TTLCache<T> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(options?: CacheOptions);
+    /**
+     * Get a value from the cache.
+     * Returns undefined if not found or expired.
+     * Updates access time for LRU tracking.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set a value in the cache.
+     * Evicts expired entries and oldest entry if at capacity.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a specific key from the cache.
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Get the current number of entries (including potentially expired ones).
+     */
+    get size(): number;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    };
+    /**
+     * Evict all expired entries.
+     */
+    private evictExpired;
+    /**
+     * Force cleanup of all expired entries.
+     * Useful for periodic maintenance.
+     */
+    cleanup(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,GAAE,YAAiB;IAKtC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAmB/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAqBhC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAQ5D;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;;OAGG;IACH,OAAO,IAAI,MAAM;CAKlB"}

package/dist/utils/cache.js

@@ -0,0 +1,134 @@
+/**
+ * Generic TTL-based LRU cache with configurable size and expiration.
+ * Provides a reusable caching utility for embeddings, metadata, and other data.
+ */
+const DEFAULT_MAX_SIZE = 100;
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * A generic LRU cache with TTL-based expiration.
+ *
+ * Features:
+ * - Configurable max size with LRU eviction
+ * - TTL-based expiration for entries
+ * - Automatic cleanup of expired entries on access
+ * - Thread-safe for single-threaded Node.js
+ *
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<number[]>({ maxSize: 50, ttlMs: 30000 });
+ * cache.set('key', [1, 2, 3]);
+ * const value = cache.get('key'); // [1, 2, 3] or undefined if expired
+ * ```
+ */
+export class TTLCache {
+    cache = new Map();
+    maxSize;
+    ttlMs;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    }
+    /**
+     * Get a value from the cache.
+     * Returns undefined if not found or expired.
+     * Updates access time for LRU tracking.
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        const now = Date.now();
+        if (now - entry.timestamp > this.ttlMs) {
+            // Entry expired
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Move to end for LRU (delete and re-insert with updated timestamp)
+        this.cache.delete(key);
+        this.cache.set(key, { value: entry.value, timestamp: now });
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache.
+     * Evicts expired entries and oldest entry if at capacity.
+     */
+    set(key, value) {
+        const now = Date.now();
+        // Remove existing entry if present (will be re-added at end)
+        this.cache.delete(key);
+        // Evict expired entries first
+        this.evictExpired(now);
+        // Evict oldest entry if still at capacity
+        if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        // Add new entry
+        this.cache.set(key, { value, timestamp: now });
+    }
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (Date.now() - entry.timestamp > this.ttlMs) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete a specific key from the cache.
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all entries from the cache.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current number of entries (including potentially expired ones).
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache statistics.
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+        };
+    }
+    /**
+     * Evict all expired entries.
+     */
+    evictExpired(now = Date.now()) {
+        for (const [key, entry] of this.cache) {
+            if (now - entry.timestamp > this.ttlMs) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Force cleanup of all expired entries.
+     * Useful for periodic maintenance.
+     */
+    cleanup() {
+        const sizeBefore = this.cache.size;
+        this.evictExpired();
+        return sizeBefore - this.cache.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

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

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Process items in parallel with controlled concurrency.
+ * Unlike Promise.all which starts all promises at once, this limits
+ * how many are running at any time.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent operations (default: 10)
+ * @returns Promise resolving to results in the same order as items
+ *
+ * @example
+ * ```typescript
+ * const results = await mapWithConcurrency(
+ *   files,
+ *   async (file) => processFile(file),
+ *   10 // max 10 concurrent file operations
+ * );
+ * ```
+ */
+export declare function mapWithConcurrency<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * Process items in batches, where each batch is processed in parallel.
+ * Useful when you want to process groups at a time with progress reporting.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param batchSize - Number of items per batch
+ * @param onBatchComplete - Optional callback after each batch completes
+ * @returns Promise resolving to results in the same order as items
+ */
+export declare function mapInBatches<T, R>(items: T[], fn: (item: T, index: number) => Promise<R>, batchSize?: number, onBatchComplete?: (completedCount: number, totalCount: number) => void): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,WAAW,GAAE,MAAW,GACvB,OAAO,CAAC,CAAC,EAAE,CAAC,CAkBd;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,CAAC,EACrC,KAAK,EAAE,CAAC,EAAE,EACV,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,SAAS,GAAE,MAAW,EACtB,eAAe,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GACrE,OAAO,CAAC,CAAC,EAAE,CAAC,CAcd"}

package/dist/utils/concurrency.js

@@ -0,0 +1,57 @@
+/**
+ * Process items in parallel with controlled concurrency.
+ * Unlike Promise.all which starts all promises at once, this limits
+ * how many are running at any time.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param concurrency - Maximum number of concurrent operations (default: 10)
+ * @returns Promise resolving to results in the same order as items
+ *
+ * @example
+ * ```typescript
+ * const results = await mapWithConcurrency(
+ *   files,
+ *   async (file) => processFile(file),
+ *   10 // max 10 concurrent file operations
+ * );
+ * ```
+ */
+export async function mapWithConcurrency(items, fn, concurrency = 10) {
+    const results = new Array(items.length);
+    let currentIndex = 0;
+    async function processNext() {
+        while (currentIndex < items.length) {
+            const index = currentIndex++;
+            results[index] = await fn(items[index], index);
+        }
+    }
+    // Start 'concurrency' number of workers
+    const workers = Array(Math.min(concurrency, items.length))
+        .fill(null)
+        .map(() => processNext());
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Process items in batches, where each batch is processed in parallel.
+ * Useful when you want to process groups at a time with progress reporting.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param batchSize - Number of items per batch
+ * @param onBatchComplete - Optional callback after each batch completes
+ * @returns Promise resolving to results in the same order as items
+ */
+export async function mapInBatches(items, fn, batchSize = 10, onBatchComplete) {
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchStartIndex = i;
+        const batchResults = await Promise.all(batch.map((item, idx) => fn(item, batchStartIndex + idx)));
+        results.push(...batchResults);
+        onBatchComplete?.(results.length, items.length);
+    }
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map