@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/tools/find/files.js

@@ -0,0 +1,142 @@
+import { join, relative } from 'node:path';
+import { statSync, lstatSync } from 'node:fs';
+import { buildGitignoreMatcher, collectGlobFiles, makeCountResult, makeFilesResult, matchesGlob, validateSearchPath } from './shared.js';
+import { summarizeError } from '../../utils/error-display.js';
+export async function executeFilesQuery(query, output, projectRoot) {
+    const validatedPath = validateSearchPath(query.path, projectRoot);
+    if (typeof validatedPath === 'object')
+        return validatedPath;
+    const basePath = validatedPath;
+    const patterns = query.patterns ?? ['**/*'];
+    const excludePatterns = query.exclude ?? [];
+    const compiledExcludes = excludePatterns.map((p) => new Bun.Glob(p));
+    const maxResults = output.max_results ?? 100;
+    const includeHidden = query.include_hidden ?? false;
+    const followSymlinks = query.follow_symlinks ?? false;
+    const respectGitignore = query.respect_gitignore !== false;
+    const modifiedAfterMs = query.modified_after ? new Date(query.modified_after).getTime() : undefined;
+    if (modifiedAfterMs !== undefined && Number.isNaN(modifiedAfterMs)) {
+        return { error: `Invalid modified_after date: ${query.modified_after}` };
+    }
+    const modifiedBeforeMs = query.modified_before ? new Date(query.modified_before).getTime() : undefined;
+    if (modifiedBeforeMs !== undefined && Number.isNaN(modifiedBeforeMs)) {
+        return { error: `Invalid modified_before date: ${query.modified_before}` };
+    }
+    const gitignoreMatcher = respectGitignore
+        ? buildGitignoreMatcher(join(projectRoot, '.gitignore'))
+        : null;
+    let hasContentRegex;
+    if (query.has_content) {
+        try {
+            hasContentRegex = new RegExp(query.has_content);
+        }
+        catch (e) {
+            return { error: `Invalid has_content regex: ${summarizeError(e)}` };
+        }
+    }
+    const SCAN_CEILING = 50_000;
+    const scannedFiles = await collectGlobFiles(basePath, patterns, includeHidden, followSymlinks);
+    const matchedFiles = new Set();
+    for (const file of scannedFiles) {
+        if (matchedFiles.size >= SCAN_CEILING)
+            break;
+        const rel = relative(basePath, file);
+        if (gitignoreMatcher && gitignoreMatcher(rel))
+            continue;
+        const excluded = compiledExcludes.some((excl) => matchesGlob(excl, file, basePath));
+        if (excluded)
+            continue;
+        matchedFiles.add(file);
+    }
+    const needStats = query.min_size !== undefined ||
+        query.max_size !== undefined ||
+        query.is_empty !== undefined ||
+        modifiedAfterMs !== undefined ||
+        modifiedBeforeMs !== undefined ||
+        query.sort_by === 'size' ||
+        query.sort_by === 'modified' ||
+        output.format === 'with_stats' ||
+        output.format === 'with_preview';
+    let entries = Array.from(matchedFiles).map((p) => ({ path: p }));
+    if (needStats) {
+        const withStats = [];
+        for (const entry of entries) {
+            try {
+                const s = followSymlinks ? statSync(entry.path) : lstatSync(entry.path);
+                entry.size = s.size;
+                entry.mtimeMs = s.mtimeMs;
+            }
+            catch {
+                // ignore stat errors
+            }
+            if (query.min_size !== undefined && (entry.size ?? 0) < query.min_size)
+                continue;
+            if (query.max_size !== undefined && (entry.size ?? 0) > query.max_size)
+                continue;
+            if (query.is_empty === true && (entry.size ?? 0) !== 0)
+                continue;
+            if (query.is_empty === false && (entry.size ?? 0) === 0)
+                continue;
+            if (modifiedAfterMs !== undefined && (entry.mtimeMs ?? 0) < modifiedAfterMs)
+                continue;
+            if (modifiedBeforeMs !== undefined && (entry.mtimeMs ?? 0) >= modifiedBeforeMs)
+                continue;
+            withStats.push(entry);
+        }
+        entries = withStats;
+    }
+    entries = entries.slice(0, maxResults);
+    if (hasContentRegex) {
+        const filtered = [];
+        for (const entry of entries) {
+            try {
+                const text = await Bun.file(entry.path).text();
+                if (hasContentRegex.test(text))
+                    filtered.push(entry);
+            }
+            catch {
+                // unreadable file
+            }
+        }
+        entries = filtered;
+    }
+    const sortBy = query.sort_by ?? 'name';
+    const sortOrder = query.sort_order ?? 'asc';
+    const dir = sortOrder === 'desc' ? -1 : 1;
+    entries.sort((a, b) => {
+        if (sortBy === 'size')
+            return ((a.size ?? 0) - (b.size ?? 0)) * dir;
+        if (sortBy === 'modified')
+            return ((a.mtimeMs ?? 0) - (b.mtimeMs ?? 0)) * dir;
+        return a.path.localeCompare(b.path) * dir;
+    });
+    const format = output.format ?? 'files_only';
+    if (format === 'count_only') {
+        return makeCountResult(entries.length);
+    }
+    if (format === 'with_stats') {
+        const result = entries.map((e) => ({
+            file: e.path,
+            size: e.size,
+            modified: e.mtimeMs !== undefined ? new Date(e.mtimeMs).toISOString() : undefined,
+        }));
+        return { files: result, count: result.length };
+    }
+    if (format === 'with_preview') {
+        const previewLines = output.preview_lines ?? 3;
+        const result = [];
+        for (const entry of entries) {
+            let preview = [];
+            try {
+                const text = await Bun.file(entry.path).text();
+                preview = text.split('\n').slice(0, previewLines);
+            }
+            catch {
+                // unreadable
+            }
+            result.push({ file: entry.path, preview });
+        }
+        return { files: result, count: result.length };
+    }
+    return makeFilesResult(entries.map((e) => e.path), entries.length);
+}

package/dist/platform/tools/find/index.d.ts

@@ -0,0 +1,4 @@
+export type { OutputFormat, SymbolKind, QueryBase, FilesQuery, ContentQuery, SymbolsQuery, ReferencesQuery, StructuralQuery, FindQuery, OutputOptions, FindInput, } from './shared.js';
+export { FindRuntimeService } from './shared.js';
+export { createFindTool } from './executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/tools/find/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/find/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/platform/tools/find/index.js

@@ -0,0 +1,2 @@
+export { FindRuntimeService } from './shared.js';
+export { createFindTool } from './executor.js';

package/dist/platform/tools/find/phased.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Create a phased find tool.
+ *
+ * Category   : `read` — find operations are non-mutating.
+ * Cancellable: `true` — directory walks and content searches can be slow;
+ *   the executor will honour an AbortSignal to interrupt long-running queries.
+ * skipPhases : `['prehook', 'posthook']` — find needs no before/after hooks
+ *   (no write audit trail, no cache invalidation).
+ *
+ * @returns A PhasedTool that delegates execution to an owned find tool instance.
+ */
+export declare function createPhasedFindTool(projectRoot: string): import("../../runtime/tools/adapter.js").PhasedTool;
+//# sourceMappingURL=phased.d.ts.map

package/dist/platform/tools/find/phased.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phased.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/find/phased.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,uDAEvD"}

package/dist/platform/tools/find/phased.js

@@ -0,0 +1,25 @@
+/**
+ * Phased wrapper for the find tool.
+ *
+ * Delegates to a freshly constructed find tool instance and adds the
+ * PhasedTool metadata required by the phased executor.
+ */
+import { asPhasedTool } from '../../runtime/tools/adapter.js';
+import { createFindTool } from './index.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a phased find tool.
+ *
+ * Category   : `read` — find operations are non-mutating.
+ * Cancellable: `true` — directory walks and content searches can be slow;
+ *   the executor will honour an AbortSignal to interrupt long-running queries.
+ * skipPhases : `['prehook', 'posthook']` — find needs no before/after hooks
+ *   (no write audit trail, no cache invalidation).
+ *
+ * @returns A PhasedTool that delegates execution to an owned find tool instance.
+ */
+export function createPhasedFindTool(projectRoot) {
+    return asPhasedTool(createFindTool(projectRoot), { category: 'read', cancellable: true, skipPhases: ['prehook', 'posthook'] });
+}

package/dist/platform/tools/find/references.d.ts

@@ -0,0 +1,3 @@
+import type { ReferencesQuery, OutputOptions } from './shared.js';
+export declare function executeReferencesQuery(query: ReferencesQuery, output: OutputOptions, projectRoot: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=references.d.ts.map

package/dist/platform/tools/find/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/find/references.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGlE,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+DlC"}

package/dist/platform/tools/find/references.js

@@ -0,0 +1,67 @@
+import { CodeIntelligence, uriToPath } from '../../intelligence/index.js';
+import { collectTextFiles, makeCountResult, makeFilesResult, makeLocationsResult, readTextFile } from './shared.js';
+export async function executeReferencesQuery(query, output, projectRoot) {
+    const maxResults = output.max_results ?? 100;
+    let locations = [];
+    const ci = new CodeIntelligence({});
+    try {
+        const lspLocations = await ci.getReferences(query.file, query.line, query.column);
+        if (lspLocations.length > 0) {
+            for (const loc of lspLocations) {
+                if (locations.length >= maxResults)
+                    break;
+                try {
+                    const filePath = uriToPath(loc.uri);
+                    locations.push({ file: filePath, line: loc.range.start.line + 1 });
+                }
+                catch {
+                    // skip invalid URIs
+                }
+            }
+            if (output.format === 'count_only')
+                return makeCountResult(locations.length);
+            if (output.format === 'files_only') {
+                const uniqueFiles = [...new Set(locations.map((l) => l.file))];
+                return makeFilesResult(uniqueFiles, locations.length);
+            }
+            return makeLocationsResult(locations, locations.length);
+        }
+    }
+    catch {
+        // LSP unavailable — fall through to grep fallback
+    }
+    if (!query.symbol) {
+        return makeLocationsResult([], 0, 'fallback');
+    }
+    let regex;
+    try {
+        regex = new RegExp(`\\b${query.symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g');
+    }
+    catch {
+        return { error: `Invalid symbol name: ${query.symbol}` };
+    }
+    const files = await collectTextFiles(projectRoot);
+    for (const file of files) {
+        if (locations.length >= maxResults)
+            break;
+        const content = await readTextFile(file);
+        if (content === null)
+            continue;
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (locations.length >= maxResults)
+                break;
+            regex.lastIndex = 0;
+            if (regex.test(lines[i])) {
+                locations.push({ file, line: i + 1 });
+            }
+        }
+    }
+    if (output.format === 'count_only')
+        return makeCountResult(locations.length, 'fallback');
+    if (output.format === 'files_only') {
+        const uniqueFiles = [...new Set(locations.map((l) => l.file))];
+        return makeFilesResult(uniqueFiles, locations.length, 'fallback');
+    }
+    return makeLocationsResult(locations, locations.length, 'fallback');
+}

package/dist/platform/tools/find/schema.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDefinition } from '../../types/tools.js';
+/**
+ * JSON Schema for the find tool's input.
+ * Supports three modes: files (glob), content (grep), symbols (regex-based extraction).
+ */
+export declare const findSchema: ToolDefinition;
+//# sourceMappingURL=schema.d.ts.map

package/dist/platform/tools/find/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/find/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,cAwQxB,CAAC"}

package/dist/platform/tools/find/schema.js

@@ -0,0 +1,261 @@
+/**
+ * JSON Schema for the find tool's input.
+ * Supports three modes: files (glob), content (grep), symbols (regex-based extraction).
+ */
+export const findSchema = {
+    name: 'find',
+    description: 'Search the codebase using glob patterns, regex content search, or symbol extraction. ' +
+        'Supports multiple queries in one call. Modes: files (glob), content (grep), symbols (regex).',
+    sideEffects: ['read_fs'],
+    concurrency: 'parallel',
+    supportsProgress: true,
+    parameters: {
+        type: 'object',
+        properties: {
+            queries: {
+                type: 'array',
+                description: 'One or more search queries to execute.',
+                items: {
+                    type: 'object',
+                    required: ['id', 'mode'],
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Unique identifier for this query. Results are keyed by this id.',
+                        },
+                        mode: {
+                            type: 'string',
+                            enum: ['files', 'content', 'symbols', 'references', 'structural'],
+                            description: 'Search mode: files (glob), content (grep), symbols (regex extraction), references (find all references via LSP with grep fallback), structural (AST pattern matching via ast-grep).',
+                        },
+                        // files mode
+                        patterns: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Glob patterns (mode: files).',
+                        },
+                        exclude: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Glob patterns to exclude (mode: files).',
+                        },
+                        min_size: {
+                            type: 'integer',
+                            minimum: 0,
+                            description: 'Minimum file size in bytes (mode: files).',
+                        },
+                        max_size: {
+                            type: 'integer',
+                            minimum: 0,
+                            description: 'Maximum file size in bytes (mode: files).',
+                        },
+                        modified_after: {
+                            type: 'string',
+                            description: 'ISO date string — include only files modified after this date (mode: files).',
+                        },
+                        modified_before: {
+                            type: 'string',
+                            description: 'ISO date string — include only files modified before this date (mode: files).',
+                        },
+                        respect_gitignore: {
+                            type: 'boolean',
+                            description: 'Exclude files matched by .gitignore patterns (mode: files). Default: true. Note: only reads the project root .gitignore — nested .gitignore files are not applied.',
+                        },
+                        sort_by: {
+                            type: 'string',
+                            enum: ['name', 'size', 'modified'],
+                            description: 'Sort results by name, size, or modified date (mode: files). Default: name.',
+                        },
+                        sort_order: {
+                            type: 'string',
+                            enum: ['asc', 'desc'],
+                            description: 'Sort direction (mode: files). Default: asc.',
+                        },
+                        has_content: {
+                            type: 'string',
+                            description: 'Regex pattern — include only files whose content matches (mode: files).',
+                        },
+                        is_empty: {
+                            type: 'boolean',
+                            description: 'When true include only empty files; when false exclude empty files (mode: files).',
+                        },
+                        follow_symlinks: {
+                            type: 'boolean',
+                            description: 'Follow symbolic links when collecting files (mode: files). Default: false.',
+                        },
+                        include_hidden: {
+                            type: 'boolean',
+                            description: 'Include hidden files and directories (dot-prefixed) (mode: files). Default: false.',
+                        },
+                        // content mode
+                        pattern: {
+                            type: 'string',
+                            description: 'Regex search pattern (mode: content).',
+                        },
+                        pattern_base64: {
+                            type: 'string',
+                            description: 'Base64-encoded regex pattern, alternative to pattern (mode: content).',
+                        },
+                        glob: {
+                            type: 'string',
+                            description: 'File filter glob pattern (mode: content).',
+                        },
+                        path: {
+                            type: 'string',
+                            description: 'Directory to search (modes: content, symbols). Defaults to project root.',
+                        },
+                        case_sensitive: {
+                            type: 'boolean',
+                            description: 'Case-sensitive matching (mode: content). Default: true.',
+                        },
+                        whole_word: {
+                            type: 'boolean',
+                            description: 'Match whole words only (mode: content).',
+                        },
+                        multiline: {
+                            type: 'boolean',
+                            description: 'Enable multiline regex (mode: content). Default: false.',
+                        },
+                        negate: {
+                            type: 'boolean',
+                            description: 'Return files that do NOT match the pattern (mode: content).',
+                        },
+                        ranked: {
+                            type: 'boolean',
+                            description: 'Sort results by relevance (mode: content). Exact matches score +10, matches in export declarations +5, recently modified files +3. Results sorted by score descending.',
+                        },
+                        preview_replace: {
+                            type: 'string',
+                            description: 'Replacement string (mode: content). When provided, shows what each matched line would look like after replacement WITHOUT writing to disk. Adds original and replaced fields to each match.',
+                        },
+                        relationships: {
+                            type: 'boolean',
+                            description: 'Include import/export relationships (mode: content). For each matched file, shows which files import it and which files it imports.',
+                        },
+                        // references mode
+                        symbol: {
+                            type: 'string',
+                            description: 'Symbol name to search for references to (mode: references).',
+                        },
+                        file: {
+                            type: 'string',
+                            description: 'File path containing the symbol (mode: references).',
+                        },
+                        line: {
+                            type: 'integer',
+                            minimum: 0,
+                            description: 'Zero-based line number of the symbol (mode: references).',
+                        },
+                        column: {
+                            type: 'integer',
+                            minimum: 0,
+                            description: 'Zero-based column offset of the symbol (mode: references).',
+                        },
+                        // symbols mode
+                        query: {
+                            type: 'string',
+                            description: 'Symbol name pattern to filter by (modes: content context, symbols).',
+                        },
+                        kinds: {
+                            type: 'array',
+                            items: {
+                                type: 'string',
+                                enum: ['function', 'class', 'interface', 'type', 'variable', 'constant', 'enum'],
+                            },
+                            description: 'Symbol kinds to include (mode: symbols).',
+                        },
+                        exported_only: {
+                            type: 'boolean',
+                            description: 'Only return exported symbols (mode: symbols). Default: false.',
+                        },
+                        include_private: {
+                            type: 'boolean',
+                            description: 'Include non-exported (private) symbols (mode: symbols). When true, overrides exported_only and includes all symbols regardless of export status.',
+                        },
+                        group_by: {
+                            type: 'string',
+                            enum: ['file', 'kind', 'none'],
+                            description: 'Group symbol results (mode: symbols). file: group by file path, kind: group by symbol kind, none: flat list (default).',
+                        },
+                        // structural mode
+                        lang: {
+                            type: 'string',
+                            enum: ['ts', 'tsx', 'js', 'jsx', 'css', 'html'],
+                            description: 'Language for AST parsing (mode: structural). Auto-detected from file extension when omitted. ' +
+                                'Supported: ts, tsx, js, jsx, css, html. Files with unrecognized extensions are skipped.',
+                        },
+                    },
+                },
+            },
+            output: {
+                type: 'object',
+                description: 'Output format options.',
+                properties: {
+                    format: {
+                        type: 'string',
+                        enum: ['count_only', 'files_only', 'locations', 'matches', 'context', 'with_stats', 'with_preview', 'signatures', 'full'],
+                        description: 'Progressive disclosure format. count_only < files_only < locations < matches < context. ' +
+                            'with_stats returns file size and modified date per file (mode: files). ' +
+                            'with_preview returns first N lines of each file (mode: files, controlled by preview_lines). ' +
+                            'signatures: include full function/method signature with params+return type (mode: symbols). ' +
+                            'full: include signature + JSDoc comment + container class/namespace (mode: symbols).',
+                    },
+                    preview_lines: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Number of lines to include in preview (format: with_preview). Default: 3.',
+                    },
+                    context_before: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Lines before each match (format: context).',
+                    },
+                    context_after: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Lines after each match (format: context).',
+                    },
+                    expand_to: {
+                        type: 'string',
+                        enum: ['line', 'block', 'function', 'class'],
+                        description: 'Expand each content match to its enclosing scope. ' +
+                            "'function' expands to the enclosing function/method, 'class' to the enclosing class. " +
+                            'Adds startLine and endLine fields to each match. ' +
+                            'Requires tree-sitter grammar for the file language; silently ignored otherwise. ' +
+                            "'line' and 'block' are accepted but currently behave the same as no expansion.",
+                    },
+                    max_results: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Maximum total results per query. Default: 100.',
+                    },
+                    max_per_item: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Maximum matches per file. Default: 10.',
+                    },
+                    max_total_matches: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Maximum total matches across all files. Default: 100.',
+                    },
+                    max_tokens: {
+                        type: 'integer',
+                        minimum: 0,
+                        description: 'Approximate token budget for the response.',
+                    },
+                    max_line_length: {
+                        type: 'integer',
+                        minimum: 1,
+                        description: 'Truncate matched lines longer than this value (mode: content). Adds "..." suffix when truncated.',
+                    },
+                },
+            },
+            parallel: {
+                type: 'boolean',
+                description: 'Execute queries concurrently. Default: true.',
+            },
+        },
+        required: ['queries'],
+    },
+};