@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/tools/fetch/trust-tiers.js

@@ -0,0 +1,294 @@
+/**
+ * Host trust tier classification.
+ *
+ * Classifies outbound HTTP request targets into one of three tiers before
+ * the request is sent. Blocked hosts are denied pre-request with an
+ * `SSRF_DENY` telemetry event. Unknown hosts receive `safe-text`
+ * sanitization. Trusted hosts may opt into `none` sanitization via config.
+ *
+ * Trust tiers:
+ *   - `trusted`  — Host is explicitly allowlisted. Sanitization may be relaxed.
+ *   - `unknown`  — Host is not in any list; apply `safe-text` sanitization.
+ *   - `blocked`  — Host matches an internal address, metadata endpoint, or
+ *                  explicit blocklist entry. Request is denied pre-flight.
+ *
+ * SSRF protections detect:
+ *   - Private IPv4 ranges (RFC 1918)
+ *   - IPv6 loopback and link-local
+ *   - Cloud metadata endpoints (169.254.x.x, metadata.google.internal, etc.)
+ *   - Localhost variants
+ *   - DNS rebinding patterns (encoded or obfuscated IP addresses)
+ */
+import { logger } from '../../utils/logger.js';
+import { hostMatchesGlob } from './host-utils.js';
+// ---------------------------------------------------------------------------
+// SSRF detection patterns
+// ---------------------------------------------------------------------------
+/** IPv4 private/loopback ranges per RFC 1918, RFC 5735. */
+const PRIVATE_IPV4_PATTERNS = [
+    // 127.0.0.0/8 — loopback
+    /^127\./,
+    // 10.0.0.0/8
+    /^10\./,
+    // 172.16.0.0/12
+    /^172\.(1[6-9]|2[0-9]|3[01])\./,
+    // 192.168.0.0/16
+    /^192\.168\./,
+    // 169.254.0.0/16 — link-local / AWS/GCP metadata
+    /^169\.254\./,
+    // 0.0.0.0 — unspecified
+    /^0\.0\.0\.0$/,
+];
+/** IPv6 loopback, link-local, and private prefixes. */
+const PRIVATE_IPV6_PATTERNS = [
+    // ::1 — loopback
+    /^::1$/i,
+    // fe80::/10 — link-local
+    /^fe[89ab][0-9a-f]:/i,
+    // fc00::/7 — unique local (fc00:: and fd00::)
+    /^f[cd][0-9a-f]{2}:/i,
+];
+/** Cloud metadata endpoints. */
+const METADATA_HOSTS = new Set([
+    // AWS EC2 Instance Metadata Service
+    'metadata.aws.internal',
+    // GCP metadata server (hostname)
+    'metadata.google.internal',
+    // Azure IMDS hostname
+    'metadata.azure.internal',
+    // Alibaba Cloud ECS metadata
+    'metadata.aliyuncs.internal',
+]);
+/** Known localhost aliases. */
+const LOCALHOST_ALIASES = new Set([
+    'localhost',
+    'localhost.localdomain',
+    'ip6-localhost',
+    'ip6-loopback',
+]);
+/**
+ * Regex patterns for detecting encoded/obfuscated IP representations
+ * used in DNS rebinding / SSRF bypass attempts.
+ * Hex and octal variants are straightforward; decimal integers require
+ * value-aware decoding via `isPrivateDecimalIp()`.
+ */
+const ENCODED_IP_HEX_OCTAL_PATTERNS = [
+    // Hex-encoded IPv4: 0xC0A80001 style
+    /^0x[0-9a-f]{1,8}$/i,
+    // Octal-encoded IPv4 segments: 0177.0.0.1 style
+    /^0[0-7]+\./,
+];
+/**
+ * Returns true if the host is a decimal integer representation of a
+ * private/loopback IPv4 address (e.g. 2130706433 = 127.0.0.1).
+ *
+ * The old pattern `/^\d{8,10}$/` was too broad — it blocked all 8-10 digit
+ * numbers regardless of whether they decoded to a private address.
+ */
+function isPrivateDecimalIp(host) {
+    if (!/^\d{1,10}$/.test(host))
+        return false;
+    const num = parseInt(host, 10);
+    if (num > 0xFFFFFFFF)
+        return false;
+    const a = (num >>> 24) & 0xFF;
+    const b = (num >>> 16) & 0xFF;
+    // Private ranges: 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x
+    return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+// ---------------------------------------------------------------------------
+// Classification helpers
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if the host is a private/loopback IPv4 address.
+ */
+function isPrivateIpv4(host) {
+    return PRIVATE_IPV4_PATTERNS.some((pattern) => pattern.test(host));
+}
+/**
+ * Returns true if the host is an IPv6 loopback or private address.
+ */
+function isPrivateIpv6(host) {
+    // Strip brackets from bracketed IPv6: [::1] -> ::1
+    const normalized = host.startsWith('[') && host.endsWith(']')
+        ? host.slice(1, -1)
+        : host;
+    return PRIVATE_IPV6_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+/**
+ * Returns true if the host uses an encoded/obfuscated IP representation
+ * commonly used to bypass naive SSRF filters.
+ */
+function isEncodedIp(host) {
+    return ENCODED_IP_HEX_OCTAL_PATTERNS.some((pattern) => pattern.test(host))
+        || isPrivateDecimalIp(host);
+}
+/**
+ * Returns true if the host matches a cloud metadata endpoint.
+ */
+function isMetadataHost(host) {
+    // Exact match
+    if (METADATA_HOSTS.has(host.toLowerCase()))
+        return true;
+    // 169.254.x.x is the link-local metadata IP (AWS/GCP use 169.254.169.254)
+    return /^169\.254\./.test(host);
+}
+/**
+ * Returns true if the host is a localhost alias.
+ */
+function isLocalhostAlias(host) {
+    return LOCALHOST_ALIASES.has(host.toLowerCase());
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Telemetry event names emitted by the trust tier classifier.
+ * These are the canonical runtime contract strings for host trust classification.
+ */
+export const TRUST_TIER_EVENTS = {
+    /** Emitted when a host trust tier has been classified (all tiers). */
+    HOST_TRUST_TIER: 'HOST_TRUST_TIER',
+    /** Emitted when a request is denied due to SSRF detection. */
+    SSRF_DENY: 'SSRF_DENY',
+};
+/**
+ * Classify the trust tier of an outbound request host.
+ *
+ * Classification order (first match wins):
+ *   1. Explicit blocklist → `blocked`
+ *   2. SSRF patterns (private IPs, metadata endpoints, localhost) → `blocked`
+ *   3. Encoded IP bypass attempts → `blocked`
+ *   4. Explicit trustlist → `trusted`
+ *   5. Default → `unknown`
+ *
+ * @param host   - Hostname or IP to classify (without port).
+ * @param config - Trust tier configuration with optional allow/deny lists.
+ * @returns      `TrustTierResult` with tier, reason, and SSRF flag.
+ */
+export function classifyHostTrustTier(host, config = {}) {
+    const normalizedHost = host.toLowerCase().trim();
+    // 1. Explicit blocklist
+    const blockedEntry = (config.blockedHosts ?? []).find((pattern) => hostMatchesGlob(normalizedHost, pattern));
+    if (blockedEntry !== undefined) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" matched explicit blocklist pattern "${blockedEntry}"`,
+            isSsrf: false,
+        };
+    }
+    // 2. SSRF — localhost aliases
+    if (isLocalhostAlias(normalizedHost)) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" is a localhost alias — SSRF risk`,
+            isSsrf: true,
+        };
+    }
+    // 3. SSRF — private IPv4
+    if (isPrivateIpv4(normalizedHost)) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" is a private IPv4 address — SSRF risk`,
+            isSsrf: true,
+        };
+    }
+    // 4. SSRF — private IPv6
+    if (isPrivateIpv6(normalizedHost)) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" is a private IPv6 address — SSRF risk`,
+            isSsrf: true,
+        };
+    }
+    // 5. SSRF — cloud metadata endpoints
+    if (isMetadataHost(normalizedHost)) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" is a cloud metadata endpoint — SSRF risk`,
+            isSsrf: true,
+        };
+    }
+    // 6. SSRF — encoded/obfuscated IP bypass
+    if (isEncodedIp(normalizedHost)) {
+        return {
+            tier: 'blocked',
+            reason: `host "${host}" uses encoded IP representation — DNS rebinding / SSRF bypass risk`,
+            isSsrf: true,
+        };
+    }
+    // 7. Explicit trustlist
+    const trustedEntry = (config.trustedHosts ?? []).find((pattern) => hostMatchesGlob(normalizedHost, pattern));
+    if (trustedEntry !== undefined) {
+        return {
+            tier: 'trusted',
+            reason: `host "${host}" matched trusted host pattern "${trustedEntry}"`,
+            isSsrf: false,
+        };
+    }
+    // 8. Default — unknown
+    return {
+        tier: 'unknown',
+        reason: `host "${host}" is not in any trust list`,
+        isSsrf: false,
+    };
+}
+/**
+ * Emit SSRF deny telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `SSRF_DENY` that can be consumed by
+ * the telemetry pipeline. This fulfils the runtime contract for the
+ * `SSRF_DENY` telemetry event in fetch sanitization.
+ *
+ * @param host     - The host that was denied.
+ * @param url      - The full URL that was attempted.
+ * @param reason   - Human-readable reason for the denial.
+ */
+export function emitSsrfDeny(host, url, reason) {
+    logger.warn('SSRF_DENY', {
+        event: TRUST_TIER_EVENTS.SSRF_DENY,
+        host,
+        url,
+        reason,
+        timestamp: Date.now(),
+    });
+}
+/**
+ * Emit host trust tier telemetry to the logger as a structured event.
+ *
+ * Emits a log entry with event name `HOST_TRUST_TIER` that can be consumed
+ * by the telemetry pipeline. This fulfils the runtime contract for the
+ * `HOST_TRUST_TIER` telemetry event in fetch sanitization.
+ *
+ * @param host   - The classified host.
+ * @param url    - The full URL being fetched.
+ * @param result - The trust tier classification result.
+ */
+export function emitHostTrustTier(host, url, result) {
+    logger.debug('HOST_TRUST_TIER', {
+        event: TRUST_TIER_EVENTS.HOST_TRUST_TIER,
+        host,
+        url,
+        tier: result.tier,
+        reason: result.reason,
+        isSsrf: result.isSsrf,
+        timestamp: Date.now(),
+    });
+}
+/**
+ * Extract the hostname from a URL string for trust tier classification.
+ *
+ * Returns `null` if the URL cannot be parsed.
+ *
+ * @param url - Full URL string (e.g. `https://example.com/path`).
+ * @returns   Hostname string (without port), or `null` on parse failure.
+ */
+export function extractHostname(url) {
+    try {
+        const parsed = new URL(url.startsWith('http') ? url : `https://${url}`);
+        return parsed.hostname;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/_internal/platform/tools/fetch/types.d.ts

@@ -0,0 +1,35 @@
+import type { FetchSanitizeMode } from './schema.js';
+export interface FetchUrlResult {
+    url: string;
+    status?: number;
+    statusText?: string;
+    contentType?: string;
+    byteSize?: number;
+    content?: string;
+    error?: string;
+    truncated?: boolean;
+    from_cache?: boolean;
+    redirected?: boolean;
+    final_url?: string;
+    duration_ms?: number;
+    tokens_used?: number;
+    sanitization_tier?: FetchSanitizeMode | 'skipped';
+    host_trust_tier?: string;
+    metadata?: {
+        headers: Record<string, string>;
+        redirected: boolean;
+        finalUrl: string;
+    };
+}
+export interface FetchOutput {
+    success: boolean;
+    error?: string;
+    results?: FetchUrlResult[];
+    summary: {
+        total: number;
+        succeeded: number;
+        failed: number;
+        total_ms?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/_internal/platform/tools/fetch/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/fetch/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH"}

package/dist/_internal/platform/tools/fetch/types.js

@@ -0,0 +1 @@
+export {};

package/dist/_internal/platform/tools/find/content.d.ts

@@ -0,0 +1,5 @@
+import type { ContentQuery, OutputOptions } from './shared.js';
+import { FindRuntimeService } from './shared.js';
+declare function executeContentQuery(query: ContentQuery, output: OutputOptions, runtime: FindRuntimeService, projectRoot: string): Promise<Record<string, unknown>>;
+export { executeContentQuery };
+//# sourceMappingURL=content.d.ts.map

package/dist/_internal/platform/tools/find/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/find/content.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAgB,MAAM,aAAa,CAAC;AAE7E,OAAO,EAOL,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AASrB,iBAAe,mBAAmB,CAChC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA0PlC;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/_internal/platform/tools/find/content.js

@@ -0,0 +1,240 @@
+import { stat as statAsync } from 'node:fs/promises';
+import { summarizeError } from '../../utils/error-display.js';
+import { collectFilesForSearch, isBinary, makeCountResult, makeFilesResult, makeLocationsResult, readTextFile, FindRuntimeService, validateSearchPath, } from './shared.js';
+async function executeContentQuery(query, output, runtime, projectRoot) {
+    const validatedPath = validateSearchPath(query.path, projectRoot);
+    if (typeof validatedPath === 'object')
+        return validatedPath;
+    const basePath = validatedPath;
+    const format = output.format ?? 'matches';
+    const maxPerFile = output.max_per_item ?? 10;
+    const maxTotal = output.max_total_matches ?? output.max_results ?? 100;
+    const ctxBefore = output.context_before ?? 0;
+    const ctxAfter = output.context_after ?? 0;
+    if (format === 'signatures' || format === 'full') {
+        return { error: `Output format '${format}' is only valid for symbols mode` };
+    }
+    let rawPattern;
+    if (query.pattern_base64) {
+        rawPattern = Buffer.from(query.pattern_base64, 'base64').toString('utf8');
+    }
+    else if (query.pattern) {
+        rawPattern = query.pattern;
+    }
+    else {
+        return { error: 'content mode requires pattern or pattern_base64' };
+    }
+    if (query.whole_word) {
+        rawPattern = `\\b(?:${rawPattern})\\b`;
+    }
+    const flags = [
+        query.case_sensitive === false ? 'i' : '',
+        query.multiline ? 'm' : '',
+        'g',
+    ].join('');
+    let regex;
+    try {
+        regex = new RegExp(rawPattern, flags);
+    }
+    catch (e) {
+        return { error: `Invalid regex: ${summarizeError(e)}` };
+    }
+    const files = await collectFilesForSearch(basePath, query.glob);
+    if (query.negate) {
+        const nonMatchingFiles = [];
+        for (const file of files) {
+            const content = await readTextFile(file);
+            if (content === null)
+                continue;
+            regex.lastIndex = 0;
+            if (!regex.test(content)) {
+                nonMatchingFiles.push(file);
+                if (nonMatchingFiles.length >= maxTotal)
+                    break;
+            }
+        }
+        if (format === 'count_only')
+            return makeCountResult(nonMatchingFiles.length);
+        return makeFilesResult(nonMatchingFiles, nonMatchingFiles.length);
+    }
+    const cacheKey = { pattern: rawPattern, glob: query.glob ?? '', path: basePath, flags };
+    const cachedEntry = runtime.searchCacheGet(cacheKey);
+    const cacheValid = cachedEntry ? await runtime.searchCacheIsValid(cachedEntry) : false;
+    let matchedFiles;
+    let totalMatches;
+    if (cacheValid && cachedEntry) {
+        matchedFiles = cachedEntry.matchedFiles;
+        totalMatches = cachedEntry.totalMatches;
+    }
+    else {
+        matchedFiles = new Map();
+        totalMatches = 0;
+        outer: for (const file of files) {
+            if (totalMatches >= maxTotal)
+                break;
+            const content = await readTextFile(file);
+            if (content === null)
+                continue;
+            if (await isBinary(file))
+                continue;
+            const lines = content.split('\n');
+            const fileMatches = [];
+            for (let i = 0; i < lines.length; i++) {
+                if (fileMatches.length >= maxPerFile)
+                    break;
+                if (totalMatches >= maxTotal)
+                    break outer;
+                regex.lastIndex = 0;
+                if (regex.test(lines[i])) {
+                    const match = { file, line: i + 1, text: lines[i] };
+                    if (format === 'context') {
+                        match.context_before = lines.slice(Math.max(0, i - ctxBefore), i);
+                        match.context_after = lines.slice(i + 1, i + 1 + ctxAfter);
+                    }
+                    fileMatches.push(match);
+                    totalMatches++;
+                }
+            }
+            if (fileMatches.length > 0) {
+                matchedFiles.set(file, { content, matches: fileMatches });
+            }
+        }
+    }
+    if (!query.ranked && !query.preview_replace && !query.relationships) {
+        const fileMtimesForCache = new Map();
+        await Promise.all(Array.from(matchedFiles.keys()).map(async (f) => {
+            try {
+                const s = await statAsync(f);
+                fileMtimesForCache.set(f, s.mtimeMs);
+            }
+            catch {
+                fileMtimesForCache.set(f, 0);
+            }
+        }));
+        runtime.searchCacheSet(cacheKey, {
+            files,
+            matchedFiles: new Map(matchedFiles),
+            totalMatches,
+            fileMtimes: fileMtimesForCache,
+        });
+    }
+    if (query.ranked) {
+        const fileMtimes = new Map();
+        await Promise.all(Array.from(matchedFiles.keys()).map(async (f) => {
+            try {
+                const s = await statAsync(f);
+                fileMtimes.set(f, s.mtimeMs);
+            }
+            catch {
+                fileMtimes.set(f, 0);
+            }
+        }));
+        const mostRecentMtime = Math.max(...Array.from(fileMtimes.values()), 0);
+        const exactPattern = query.pattern_base64
+            ? Buffer.from(query.pattern_base64, 'base64').toString('utf8')
+            : (query.pattern ?? '');
+        const scoredEntries = [];
+        for (const [file, { matches }] of matchedFiles) {
+            let fileScore = 0;
+            const mtime = fileMtimes.get(file) ?? 0;
+            if (mostRecentMtime > 0 && mtime >= mostRecentMtime * 0.95)
+                fileScore += 3;
+            for (const m of matches) {
+                if (m.text.includes(exactPattern))
+                    fileScore += 10;
+                if (/^export\s/.test(m.text.trimStart()))
+                    fileScore += 5;
+            }
+            scoredEntries.push({ file, matches, score: fileScore });
+        }
+        scoredEntries.sort((a, b) => b.score - a.score);
+        const sortedEntries = scoredEntries.map(({ file, matches }) => {
+            const original = matchedFiles.get(file);
+            return [file, { content: original?.content ?? '', matches }];
+        });
+        matchedFiles = new Map(sortedEntries);
+    }
+    const expandTo = output.expand_to;
+    if (expandTo === 'function' || expandTo === 'class') {
+        const ci = new (await import('../../intelligence/index.js')).CodeIntelligence({});
+        for (const [file, { content, matches }] of matchedFiles) {
+            for (const m of matches) {
+                try {
+                    const scope = await ci.getEnclosingScope(file, content, m.line);
+                    if (scope) {
+                        m.startLine = scope.startLine;
+                        m.endLine = scope.endLine;
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    if (format === 'count_only') {
+        return makeCountResult(totalMatches, undefined, matchedFiles.size);
+    }
+    if (format === 'files_only') {
+        return makeFilesResult(Array.from(matchedFiles.keys()), matchedFiles.size);
+    }
+    if (format === 'locations') {
+        const locations = [];
+        for (const [file, { matches }] of matchedFiles) {
+            for (const m of matches) {
+                locations.push({ file, line: m.line });
+            }
+        }
+        return makeLocationsResult(locations, totalMatches);
+    }
+    if (format === 'matches' || format === 'context') {
+        const results = [];
+        for (const [, { matches }] of matchedFiles) {
+            for (const m of matches) {
+                let displayText = m.text;
+                let replacedText;
+                if (query.preview_replace !== undefined) {
+                    try {
+                        const replaceRegex = new RegExp(rawPattern, flags);
+                        replacedText = m.text.replace(replaceRegex, query.preview_replace);
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                if (output.max_line_length && displayText.length > output.max_line_length) {
+                    displayText = displayText.slice(0, output.max_line_length) + '...';
+                }
+                if (replacedText !== undefined && output.max_line_length && replacedText.length > output.max_line_length) {
+                    replacedText = replacedText.slice(0, output.max_line_length) + '...';
+                }
+                const entry = { file: m.file, line: m.line, text: displayText };
+                if (replacedText !== undefined)
+                    entry.replaced = replacedText;
+                if (m.startLine !== undefined)
+                    entry.startLine = m.startLine;
+                if (m.endLine !== undefined)
+                    entry.endLine = m.endLine;
+                if (format === 'context') {
+                    entry.context_before = m.context_before;
+                    entry.context_after = m.context_after;
+                }
+                results.push(entry);
+            }
+        }
+        if (query.relationships) {
+            const importGraph = await runtime.getImportGraph(projectRoot);
+            const relMap = {};
+            for (const file of matchedFiles.keys()) {
+                relMap[file] = {
+                    imports: importGraph.findImports(file),
+                    importedBy: importGraph.findDependents(file),
+                };
+            }
+            return { matches: results, count: totalMatches, relationships: relMap };
+        }
+        return { matches: results, count: totalMatches };
+    }
+    return makeCountResult(totalMatches);
+}
+export { executeContentQuery };

package/dist/_internal/platform/tools/find/executor.d.ts

@@ -0,0 +1,5 @@
+import type { Tool } from '../../types/tools.js';
+import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
+import { FindRuntimeService } from './shared.js';
+export declare function createFindTool(projectRoot: string, featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null, runtime?: FindRuntimeService): Tool;
+//# sourceMappingURL=executor.d.ts.map

package/dist/_internal/platform/tools/find/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/find/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AASjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,EAC3D,OAAO,qBAA2B,GACjC,IAAI,CAuEN"}

package/dist/_internal/platform/tools/find/executor.js

@@ -0,0 +1,76 @@
+import { appendSchemaFingerprint } from '../shared/schema-fingerprint.js';
+import { findSchema } from './schema.js';
+import { executeFilesQuery } from './files.js';
+import { executeContentQuery } from './content.js';
+import { executeReferencesQuery } from './references.js';
+import { executeStructuralQuery } from './structural.js';
+import { executeSymbolsQuery } from './symbols.js';
+import { FindRuntimeService } from './shared.js';
+import { summarizeError } from '../../utils/error-display.js';
+export function createFindTool(projectRoot, featureFlags, runtime = new FindRuntimeService()) {
+    if (typeof projectRoot !== 'string' || projectRoot.trim().length === 0) {
+        throw new Error('createFindTool requires projectRoot');
+    }
+    return {
+        definition: findSchema,
+        async execute(args) {
+            try {
+                if (!Array.isArray(args.queries) || args.queries.length === 0) {
+                    return { success: false, error: 'Missing or empty "queries" array' };
+                }
+                const input = args;
+                const output = input.output ?? {};
+                const parallel = input.parallel !== false;
+                const runQuery = async (query) => {
+                    let result;
+                    switch (query.mode) {
+                        case 'files':
+                            result = await executeFilesQuery(query, output, projectRoot);
+                            break;
+                        case 'content':
+                            result = await executeContentQuery(query, output, runtime, projectRoot);
+                            break;
+                        case 'symbols':
+                            result = await executeSymbolsQuery(query, output, projectRoot);
+                            break;
+                        case 'references':
+                            result = await executeReferencesQuery(query, output, projectRoot);
+                            break;
+                        case 'structural':
+                            result = await executeStructuralQuery(query, output, projectRoot);
+                            break;
+                        default: {
+                            const exhaustive = query;
+                            result = { error: `Unknown mode: ${exhaustive.mode}` };
+                        }
+                    }
+                    return [query.id, appendSchemaFingerprint(result, 'find', query.mode, { featureFlags })];
+                };
+                let pairs;
+                if (parallel) {
+                    pairs = await Promise.all(input.queries.map(runQuery));
+                }
+                else {
+                    pairs = [];
+                    for (const query of input.queries) {
+                        pairs.push(await runQuery(query));
+                    }
+                }
+                const results = {};
+                for (const [id, result] of pairs) {
+                    results[id] = result;
+                }
+                const finalResults = input.queries.length > 1
+                    ? appendSchemaFingerprint(results, 'find', 'multi', { featureFlags })
+                    : results;
+                return { success: true, output: JSON.stringify(finalResults) };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: summarizeError(err),
+                };
+            }
+        },
+    };
+}

package/dist/_internal/platform/tools/find/files.d.ts

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

package/dist/_internal/platform/tools/find/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/tools/find/files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI7D,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8IlC"}