@anthropic-field/core 0.1.0

package/dist/src/utils/googleQuotaErrors.js

@@ -0,0 +1,250 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { parseGoogleApiError } from './googleErrors.js';
+import { getErrorStatus, ModelNotFoundError } from './httpErrors.js';
+/**
+ * A non-retryable error indicating a hard quota limit has been reached (e.g., daily limit).
+ */
+export class TerminalQuotaError extends Error {
+    cause;
+    retryDelayMs;
+    constructor(message, cause, retryDelaySeconds) {
+        super(message);
+        this.cause = cause;
+        this.name = 'TerminalQuotaError';
+        this.retryDelayMs = retryDelaySeconds
+            ? retryDelaySeconds * 1000
+            : undefined;
+    }
+}
+/**
+ * A retryable error indicating a temporary quota issue (e.g., per-minute limit).
+ */
+export class RetryableQuotaError extends Error {
+    cause;
+    retryDelayMs;
+    constructor(message, cause, retryDelaySeconds) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RetryableQuotaError';
+        this.retryDelayMs = retryDelaySeconds
+            ? retryDelaySeconds * 1000
+            : undefined;
+    }
+}
+/**
+ * An error indicating that user validation is required to continue.
+ */
+export class ValidationRequiredError extends Error {
+    cause;
+    validationLink;
+    validationDescription;
+    learnMoreUrl;
+    userHandled = false;
+    constructor(message, cause, validationLink, validationDescription, learnMoreUrl) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ValidationRequiredError';
+        this.validationLink = validationLink;
+        this.validationDescription = validationDescription;
+        this.learnMoreUrl = learnMoreUrl;
+    }
+}
+/**
+ * Parses a duration string (e.g., "34.074824224s", "60s", "900ms") and returns the time in seconds.
+ * @param duration The duration string to parse.
+ * @returns The duration in seconds, or null if parsing fails.
+ */
+function parseDurationInSeconds(duration) {
+    if (duration.endsWith('ms')) {
+        const milliseconds = parseFloat(duration.slice(0, -2));
+        return isNaN(milliseconds) ? null : milliseconds / 1000;
+    }
+    if (duration.endsWith('s')) {
+        const seconds = parseFloat(duration.slice(0, -1));
+        return isNaN(seconds) ? null : seconds;
+    }
+    return null;
+}
+/**
+ * Valid Cloud Code API domains for VALIDATION_REQUIRED errors.
+ */
+const CLOUDCODE_DOMAINS = [
+    'cloudcode-pa.googleapis.com',
+    'staging-cloudcode-pa.googleapis.com',
+    'autopush-cloudcode-pa.googleapis.com',
+];
+/**
+ * Checks if a 403 error requires user validation and extracts validation details.
+ *
+ * @param googleApiError The parsed Google API error to check.
+ * @returns A `ValidationRequiredError` if validation is required, otherwise `null`.
+ */
+function classifyValidationRequiredError(googleApiError) {
+    const errorInfo = googleApiError.details.find((d) => d['@type'] === 'type.googleapis.com/google.rpc.ErrorInfo');
+    if (!errorInfo) {
+        return null;
+    }
+    if (!CLOUDCODE_DOMAINS.includes(errorInfo.domain) ||
+        errorInfo.reason !== 'VALIDATION_REQUIRED') {
+        return null;
+    }
+    // Try to extract validation info from Help detail first
+    const helpDetail = googleApiError.details.find((d) => d['@type'] === 'type.googleapis.com/google.rpc.Help');
+    let validationLink;
+    let validationDescription;
+    let learnMoreUrl;
+    if (helpDetail?.links && helpDetail.links.length > 0) {
+        // First link is the validation link, extract description and URL
+        const validationLinkInfo = helpDetail.links[0];
+        validationLink = validationLinkInfo.url;
+        validationDescription = validationLinkInfo.description;
+        // Look for "Learn more" link - identified by description or support.google.com hostname
+        const learnMoreLink = helpDetail.links.find((link) => {
+            if (link.description.toLowerCase().trim() === 'learn more')
+                return true;
+            const parsed = URL.parse(link.url);
+            return parsed?.hostname === 'support.google.com';
+        });
+        if (learnMoreLink) {
+            learnMoreUrl = learnMoreLink.url;
+        }
+    }
+    // Fallback to ErrorInfo metadata if Help detail not found
+    if (!validationLink) {
+        validationLink = errorInfo.metadata?.['validation_link'];
+    }
+    return new ValidationRequiredError(googleApiError.message, googleApiError, validationLink, validationDescription, learnMoreUrl);
+}
+/**
+ * Analyzes a caught error and classifies it as a specific error type if applicable.
+ *
+ * Classification logic:
+ * - 404 errors are classified as `ModelNotFoundError`.
+ * - 403 errors with `VALIDATION_REQUIRED` from cloudcode-pa domains are classified
+ *   as `ValidationRequiredError`.
+ * - 429 errors are classified as either `TerminalQuotaError` or `RetryableQuotaError`:
+ *   - CloudCode API: `RATE_LIMIT_EXCEEDED` → `RetryableQuotaError`, `QUOTA_EXHAUSTED` → `TerminalQuotaError`.
+ *   - If the error indicates a daily limit (in QuotaFailure), it's a `TerminalQuotaError`.
+ *   - If the error has a retry delay, it's a `RetryableQuotaError`.
+ *   - If the error indicates a per-minute limit, it's a `RetryableQuotaError`.
+ *   - If the error message contains the phrase "Please retry in X[s|ms]", it's a `RetryableQuotaError`.
+ *
+ * @param error The error to classify.
+ * @returns A classified error or the original `unknown` error.
+ */
+export function classifyGoogleError(error) {
+    const googleApiError = parseGoogleApiError(error);
+    const status = googleApiError?.code ?? getErrorStatus(error);
+    if (status === 404) {
+        const message = googleApiError?.message ||
+            (error instanceof Error ? error.message : 'Model not found');
+        return new ModelNotFoundError(message, status);
+    }
+    // Check for 403 VALIDATION_REQUIRED errors from Cloud Code API
+    if (status === 403 && googleApiError) {
+        const validationError = classifyValidationRequiredError(googleApiError);
+        if (validationError) {
+            return validationError;
+        }
+    }
+    if (!googleApiError ||
+        googleApiError.code !== 429 ||
+        googleApiError.details.length === 0) {
+        // Fallback: try to parse the error message for a retry delay
+        const errorMessage = googleApiError?.message ||
+            (error instanceof Error ? error.message : String(error));
+        const match = errorMessage.match(/Please retry in ([0-9.]+(?:ms|s))/);
+        if (match?.[1]) {
+            const retryDelaySeconds = parseDurationInSeconds(match[1]);
+            if (retryDelaySeconds !== null) {
+                return new RetryableQuotaError(errorMessage, googleApiError ?? {
+                    code: 429,
+                    message: errorMessage,
+                    details: [],
+                }, retryDelaySeconds);
+            }
+        }
+        else if (status === 429) {
+            // Fallback: If it is a 429 but doesn't have a specific "retry in" message,
+            // assume it is a temporary rate limit and retry after 5 sec (same as DEFAULT_RETRY_OPTIONS).
+            return new RetryableQuotaError(errorMessage, googleApiError ?? {
+                code: 429,
+                message: errorMessage,
+                details: [],
+            });
+        }
+        return error; // Not a 429 error we can handle with structured details or a parsable retry message.
+    }
+    const quotaFailure = googleApiError.details.find((d) => d['@type'] === 'type.googleapis.com/google.rpc.QuotaFailure');
+    const errorInfo = googleApiError.details.find((d) => d['@type'] === 'type.googleapis.com/google.rpc.ErrorInfo');
+    const retryInfo = googleApiError.details.find((d) => d['@type'] === 'type.googleapis.com/google.rpc.RetryInfo');
+    // 1. Check for long-term limits in QuotaFailure or ErrorInfo
+    if (quotaFailure) {
+        for (const violation of quotaFailure.violations) {
+            const quotaId = violation.quotaId ?? '';
+            if (quotaId.includes('PerDay') || quotaId.includes('Daily')) {
+                return new TerminalQuotaError(`You have exhausted your daily quota on this model.`, googleApiError);
+            }
+        }
+    }
+    let delaySeconds;
+    if (retryInfo?.retryDelay) {
+        const parsedDelay = parseDurationInSeconds(retryInfo.retryDelay);
+        if (parsedDelay) {
+            delaySeconds = parsedDelay;
+        }
+    }
+    if (errorInfo) {
+        // New Cloud Code API quota handling
+        if (errorInfo.domain) {
+            const validDomains = [
+                'cloudcode-pa.googleapis.com',
+                'staging-cloudcode-pa.googleapis.com',
+                'autopush-cloudcode-pa.googleapis.com',
+            ];
+            if (validDomains.includes(errorInfo.domain)) {
+                if (errorInfo.reason === 'RATE_LIMIT_EXCEEDED') {
+                    return new RetryableQuotaError(`${googleApiError.message}`, googleApiError, delaySeconds ?? 10);
+                }
+                if (errorInfo.reason === 'QUOTA_EXHAUSTED') {
+                    return new TerminalQuotaError(`${googleApiError.message}`, googleApiError, delaySeconds);
+                }
+            }
+        }
+    }
+    // 2. Check for delays in RetryInfo
+    if (retryInfo?.retryDelay && delaySeconds) {
+        return new RetryableQuotaError(`${googleApiError.message}\nSuggested retry after ${retryInfo.retryDelay}.`, googleApiError, delaySeconds);
+    }
+    // 3. Check for short-term limits in QuotaFailure or ErrorInfo
+    if (quotaFailure) {
+        for (const violation of quotaFailure.violations) {
+            const quotaId = violation.quotaId ?? '';
+            if (quotaId.includes('PerMinute')) {
+                return new RetryableQuotaError(`${googleApiError.message}\nSuggested retry after 60s.`, googleApiError, 60);
+            }
+        }
+    }
+    if (errorInfo) {
+        const quotaLimit = errorInfo.metadata?.['quota_limit'] ?? '';
+        if (quotaLimit.includes('PerMinute')) {
+            return new RetryableQuotaError(`${errorInfo.reason}\nSuggested retry after 60s.`, googleApiError, 60);
+        }
+    }
+    // If we reached this point and the status is still 429, we return retryable.
+    if (status === 429) {
+        const errorMessage = googleApiError?.message ||
+            (error instanceof Error ? error.message : String(error));
+        return new RetryableQuotaError(errorMessage, googleApiError ?? {
+            code: 429,
+            message: errorMessage,
+            details: [],
+        });
+    }
+    return error; // Fallback to original error if no specific classification fits.
+}
+//# sourceMappingURL=googleQuotaErrors.js.map

package/dist/src/utils/googleQuotaErrors.js.map

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

package/dist/src/utils/httpErrors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface HttpError extends Error {
+    status?: number;
+}
+/**
+ * Extracts the HTTP status code from an error object.
+ * @param error The error object.
+ * @returns The HTTP status code, or undefined if not found.
+ */
+export declare function getErrorStatus(error: unknown): number | undefined;
+export declare class ModelNotFoundError extends Error {
+    code: number;
+    constructor(message: string, code?: number);
+}

package/dist/src/utils/httpErrors.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Extracts the HTTP status code from an error object.
+ * @param error The error object.
+ * @returns The HTTP status code, or undefined if not found.
+ */
+export function getErrorStatus(error) {
+    if (typeof error === 'object' && error !== null) {
+        if ('status' in error && typeof error.status === 'number') {
+            return error.status;
+        }
+        // Check for error.response.status (common in axios errors)
+        if ('response' in error &&
+            typeof error.response === 'object' &&
+            error.response !== null) {
+            const response = error.response;
+            if ('status' in response && typeof response.status === 'number') {
+                return response.status;
+            }
+        }
+    }
+    return undefined;
+}
+export class ModelNotFoundError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'ModelNotFoundError';
+        this.code = code ? code : 404;
+    }
+}
+//# sourceMappingURL=httpErrors.js.map

package/dist/src/utils/httpErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpErrors.js","sourceRoot":"","sources":["../../../src/utils/httpErrors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,IAAI,QAAQ,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QACD,2DAA2D;QAC3D,IACE,UAAU,IAAI,KAAK;YACnB,OAAQ,KAAgC,CAAC,QAAQ,KAAK,QAAQ;YAC7D,KAAgC,CAAC,QAAQ,KAAK,IAAI,EACnD,CAAC;YACD,MAAM,QAAQ,GACZ,KACD,CAAC,QAAQ,CAAC;YACX,IAAI,QAAQ,IAAI,QAAQ,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAChE,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,IAAI,CAAS;IACb,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IAChC,CAAC;CACF"}

package/dist/src/utils/ignoreFileParser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export interface IgnoreFileFilter {
+    isIgnored(filePath: string): boolean;
+    getPatterns(): string[];
+    getIgnoreFilePaths(): string[];
+    hasPatterns(): boolean;
+}
+/**
+ * An ignore file parser that reads the ignore files from the project root.
+ */
+export declare class IgnoreFileParser implements IgnoreFileFilter {
+    private projectRoot;
+    private patterns;
+    private ig;
+    private readonly fileNames;
+    constructor(projectRoot: string, input: string | string[], isPatterns?: boolean);
+    private loadPatternsFromFiles;
+    private parseIgnoreFile;
+    isIgnored(filePath: string): boolean;
+    getPatterns(): string[];
+    getIgnoreFilePaths(): string[];
+    /**
+     * Returns true if at least one ignore file exists and has patterns.
+     */
+    hasPatterns(): boolean;
+}

package/dist/src/utils/ignoreFileParser.js

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ignore from 'ignore';
+import { debugLogger } from './debugLogger.js';
+/**
+ * An ignore file parser that reads the ignore files from the project root.
+ */
+export class IgnoreFileParser {
+    projectRoot;
+    patterns = [];
+    ig = ignore();
+    fileNames;
+    constructor(projectRoot, 
+    // The order matters: files listed earlier have higher priority.
+    // It can be a single file name/pattern or an array of file names/patterns.
+    input, isPatterns = false) {
+        this.projectRoot = path.resolve(projectRoot);
+        if (isPatterns) {
+            this.fileNames = [];
+            const patterns = Array.isArray(input) ? input : [input];
+            this.patterns.push(...patterns);
+            this.ig.add(patterns);
+        }
+        else {
+            this.fileNames = Array.isArray(input) ? input : [input];
+            this.loadPatternsFromFiles();
+        }
+    }
+    loadPatternsFromFiles() {
+        // Iterate in reverse order so that the first file in the list is processed last.
+        // This gives the first file the highest priority, as patterns added later override earlier ones.
+        for (const fileName of [...this.fileNames].reverse()) {
+            const patterns = this.parseIgnoreFile(fileName);
+            this.patterns.push(...patterns);
+            this.ig.add(patterns);
+        }
+    }
+    parseIgnoreFile(fileName) {
+        const patternsFilePath = path.join(this.projectRoot, fileName);
+        let content;
+        try {
+            content = fs.readFileSync(patternsFilePath, 'utf-8');
+        }
+        catch (_error) {
+            debugLogger.debug(`Ignore file not found: ${patternsFilePath}, continue without it.`);
+            return [];
+        }
+        debugLogger.debug(`Loading ignore patterns from: ${patternsFilePath}`);
+        return (content ?? '')
+            .split('\n')
+            .map((p) => p.trim())
+            .filter((p) => p !== '' && !p.startsWith('#'));
+    }
+    isIgnored(filePath) {
+        if (this.patterns.length === 0) {
+            return false;
+        }
+        if (!filePath || typeof filePath !== 'string') {
+            return false;
+        }
+        if (filePath.startsWith('\\') ||
+            filePath === '/' ||
+            filePath.includes('\0')) {
+            return false;
+        }
+        const resolved = path.resolve(this.projectRoot, filePath);
+        const relativePath = path.relative(this.projectRoot, resolved);
+        if (relativePath === '' || relativePath.startsWith('..')) {
+            return false;
+        }
+        // Even in windows, Ignore expects forward slashes.
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        if (normalizedPath.startsWith('/') || normalizedPath === '') {
+            return false;
+        }
+        return this.ig.ignores(normalizedPath);
+    }
+    getPatterns() {
+        return this.patterns;
+    }
+    getIgnoreFilePaths() {
+        return this.fileNames
+            .slice()
+            .reverse()
+            .map((fileName) => path.join(this.projectRoot, fileName))
+            .filter((filePath) => fs.existsSync(filePath));
+    }
+    /**
+     * Returns true if at least one ignore file exists and has patterns.
+     */
+    hasPatterns() {
+        return this.patterns.length > 0;
+    }
+}
+//# sourceMappingURL=ignoreFileParser.js.map

package/dist/src/utils/ignoreFileParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignoreFileParser.js","sourceRoot":"","sources":["../../../src/utils/ignoreFileParser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAS/C;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,WAAW,CAAS;IACpB,QAAQ,GAAa,EAAE,CAAC;IACxB,EAAE,GAAG,MAAM,EAAE,CAAC;IACL,SAAS,CAAW;IAErC,YACE,WAAmB;IACnB,gEAAgE;IAChE,2EAA2E;IAC3E,KAAwB,EACxB,UAAU,GAAG,KAAK;QAElB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACxD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACxD,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;IAEO,qBAAqB;QAC3B,iFAAiF;QACjF,iGAAiG;QACjG,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;YAChD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,eAAe,CAAC,QAAgB;QACtC,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC/D,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,WAAW,CAAC,KAAK,CACf,0BAA0B,gBAAgB,wBAAwB,CACnE,CAAC;YACF,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,WAAW,CAAC,KAAK,CAAC,iCAAiC,gBAAgB,EAAE,CAAC,CAAC;QAEvE,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;aACnB,KAAK,CAAC,IAAI,CAAC;aACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,SAAS,CAAC,QAAgB;QACxB,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IACE,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC;YACzB,QAAQ,KAAK,GAAG;YAChB,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EACvB,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAE/D,IAAI,YAAY,KAAK,EAAE,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,mDAAmD;QACnD,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAExD,IAAI,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,cAAc,KAAK,EAAE,EAAE,CAAC;YAC5D,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,kBAAkB;QAChB,OAAO,IAAI,CAAC,SAAS;aAClB,KAAK,EAAE;aACP,OAAO,EAAE;aACT,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;aACxD,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,CAAC;CACF"}

package/dist/src/utils/ignorePatterns.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Config } from '../config/config.js';
+/**
+ * Common ignore patterns used across multiple tools for basic exclusions.
+ * These are the most commonly ignored directories in development projects.
+ */
+export declare const COMMON_IGNORE_PATTERNS: string[];
+/**
+ * Binary file extension patterns that are typically excluded from text processing.
+ */
+export declare const BINARY_FILE_PATTERNS: string[];
+/**
+ * Media file patterns that require special handling in tools like read-many-files.
+ * These files can be processed as inlineData when explicitly requested.
+ */
+export declare const MEDIA_FILE_PATTERNS: string[];
+/**
+ * Common directory patterns that are typically ignored in development projects.
+ */
+export declare const COMMON_DIRECTORY_EXCLUDES: string[];
+/**
+ * Python-specific patterns.
+ */
+export declare const PYTHON_EXCLUDES: string[];
+/**
+ * System and environment file patterns.
+ */
+export declare const SYSTEM_FILE_EXCLUDES: string[];
+/**
+ * Comprehensive file exclusion patterns combining all common ignore patterns.
+ * These patterns are compatible with glob ignore patterns.
+ * Note: Media files (PDF, images) are not excluded here as they need special handling in read-many-files.
+ */
+export declare const DEFAULT_FILE_EXCLUDES: string[];
+/**
+ * Options for configuring file exclusion patterns.
+ */
+export interface ExcludeOptions {
+    /**
+     * Whether to include default exclusion patterns. Defaults to true.
+     */
+    includeDefaults?: boolean;
+    /**
+     * Additional custom patterns from configuration.
+     */
+    customPatterns?: string[];
+    /**
+     * Additional patterns provided at runtime (e.g., from CLI arguments).
+     */
+    runtimePatterns?: string[];
+    /**
+     * Whether to include dynamic patterns like the current Gemini MD filename. Defaults to true.
+     */
+    includeDynamicPatterns?: boolean;
+}
+/**
+ * Centralized file exclusion utility that provides configurable and extensible
+ * file exclusion patterns for different tools and use cases.
+ */
+export declare class FileExclusions {
+    private config?;
+    constructor(config?: Config | undefined);
+    /**
+     * Gets core ignore patterns for basic file operations like glob.
+     * These are the minimal essential patterns that should almost always be excluded.
+     */
+    getCoreIgnorePatterns(): string[];
+    /**
+     * Gets comprehensive default exclusion patterns for operations like read-many-files.
+     * Includes all standard exclusions: directories, binary files, system files, etc.
+     */
+    getDefaultExcludePatterns(options?: ExcludeOptions): string[];
+    /**
+     * Gets exclude patterns for read-many-files tool with legacy compatibility.
+     * This maintains the same behavior as the previous getDefaultExcludes() function.
+     */
+    getReadManyFilesExcludes(additionalExcludes?: string[]): string[];
+    /**
+     * Gets exclude patterns for glob tool operations.
+     * Uses core patterns by default but can be extended with additional patterns.
+     */
+    getGlobExcludes(additionalExcludes?: string[]): string[];
+    /**
+     * Builds exclude patterns with full customization options.
+     * This is the most flexible method for advanced use cases.
+     */
+    buildExcludePatterns(options: ExcludeOptions): string[];
+}
+/**
+ * Extracts file extensions from glob patterns.
+ * Converts patterns like glob/*.exe to .exe
+ * Handles brace expansion like glob/*.{js,ts} to .js and .ts
+ */
+export declare function extractExtensionsFromPatterns(patterns: string[]): string[];
+/**
+ * Binary file extensions extracted from BINARY_FILE_PATTERNS for quick lookup.
+ * Additional extensions not covered by the patterns are included for completeness.
+ */
+export declare const BINARY_EXTENSIONS: string[];