@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/google-mail.d.ts

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import type { GoogleAuth } from './google-auth.js';
+export type MailMessage = {
+    id: string;
+    threadId: string;
+    labelIds: string[];
+    snippet: string;
+    subject: string;
+    from: string;
+    to: string;
+    cc?: string;
+    date: string;
+    body: string;
+    bodyHtml?: string;
+    isUnread: boolean;
+    hasAttachments: boolean;
+    attachments: MailAttachment[];
+};
+export type MailAttachment = {
+    filename: string;
+    mimeType: string;
+    size: number;
+    attachmentId: string;
+};
+export type MailThread = {
+    id: string;
+    snippet: string;
+    historyId: string;
+    messages: MailMessage[];
+};
+export type MailLabel = {
+    id: string;
+    name: string;
+    type: string;
+    messagesTotal?: number;
+    messagesUnread?: number;
+};
+export type SearchMailOptions = {
+    query?: string;
+    from?: string;
+    to?: string;
+    subject?: string;
+    after?: string;
+    before?: string;
+    hasAttachment?: boolean;
+    label?: string;
+    isUnread?: boolean;
+    maxResults?: number;
+    pageToken?: string;
+};
+export type MailMessageList = {
+    messages: MailMessage[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+};
+export declare const GoogleMailStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    lastQuery: z.ZodOptional<z.ZodString>;
+    lastResultCount: z.ZodOptional<z.ZodNumber>;
+    lastError: z.ZodOptional<z.ZodString>;
+    watchExpiration: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type GoogleMailState = z.infer<typeof GoogleMailStateSchema>;
+export declare const GoogleMailOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    auth: z.ZodOptional<z.ZodAny>;
+    userId: z.ZodOptional<z.ZodString>;
+    pollInterval: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<{
+        metadata: "metadata";
+        full: "full";
+        minimal: "minimal";
+        raw: "raw";
+    }>>;
+}, z.core.$strip>;
+export type GoogleMailOptions = z.infer<typeof GoogleMailOptionsSchema>;
+export declare const GoogleMailEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    messagesFetched: z.ZodTuple<[z.ZodNumber], null>;
+    newMail: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+    watchStarted: z.ZodTuple<[], null>;
+    watchStopped: z.ZodTuple<[], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * Google Mail feature for searching, reading, and watching Gmail messages.
+ *
+ * Depends on the googleAuth feature for authentication. Creates a Gmail v1 API
+ * client lazily. Supports Gmail search query syntax, individual message reading,
+ * and polling-based new mail detection with event emission.
+ *
+ * @example
+ * ```typescript
+ * const mail = container.feature('googleMail')
+ *
+ * // Search by sender
+ * const fromBoss = await mail.search({ from: 'boss@company.com' })
+ *
+ * // Use Gmail query string
+ * const unread = await mail.search({ query: 'is:unread category:primary' })
+ *
+ * // Read a specific message
+ * const msg = await mail.getMessage('message-id-here')
+ *
+ * // Get a full thread
+ * const thread = await mail.getThread('thread-id-here')
+ *
+ * // List labels
+ * const labels = await mail.listLabels()
+ *
+ * // Watch for new mail (polls and emits 'newMail' events)
+ * mail.on('newMail', (messages) => {
+ *   console.log(`Got ${messages.length} new messages!`)
+ * })
+ * await mail.startWatching()
+ *
+ * // Stop watching
+ * mail.stopWatching()
+ * ```
+ */
+export declare class GoogleMail extends Feature<GoogleMailState, GoogleMailOptions> {
+    static shortcut: "features.googleMail";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        lastQuery: z.ZodOptional<z.ZodString>;
+        lastResultCount: z.ZodOptional<z.ZodNumber>;
+        lastError: z.ZodOptional<z.ZodString>;
+        watchExpiration: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        auth: z.ZodOptional<z.ZodAny>;
+        userId: z.ZodOptional<z.ZodString>;
+        pollInterval: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodOptional<z.ZodEnum<{
+            metadata: "metadata";
+            full: "full";
+            minimal: "minimal";
+            raw: "raw";
+        }>>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        messagesFetched: z.ZodTuple<[z.ZodNumber], null>;
+        newMail: z.ZodTuple<[z.ZodArray<z.ZodAny>], null>;
+        watchStarted: z.ZodTuple<[], null>;
+        watchStopped: z.ZodTuple<[], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    private _gmail?;
+    private _watchTimer?;
+    private _lastHistoryId?;
+    get initialState(): GoogleMailState;
+    /** Access the google-auth feature lazily. */
+    get auth(): GoogleAuth;
+    /** Default user ID from options or 'me'. */
+    get userId(): string;
+    /** Default message format from options or 'full'. */
+    get defaultFormat(): 'full' | 'metadata' | 'minimal' | 'raw';
+    /** Polling interval from options or 30 seconds. */
+    get pollInterval(): number;
+    /** Get or create the Gmail v1 API client. */
+    private getGmail;
+    /**
+     * Search for messages using Gmail query syntax and/or structured filters.
+     *
+     * @param options - Search filters including query, from, to, subject, date ranges
+     * @returns Messages array with optional nextPageToken
+     */
+    search(options?: SearchMailOptions): Promise<MailMessageList>;
+    /**
+     * Get a single message by ID.
+     *
+     * @param messageId - The message ID
+     * @param format - Message format (defaults to options.format or 'full')
+     * @returns The full mail message
+     */
+    getMessage(messageId: string, format?: 'full' | 'metadata' | 'minimal' | 'raw'): Promise<MailMessage>;
+    /**
+     * Get a full thread with all its messages.
+     *
+     * @param threadId - The thread ID
+     * @returns The thread with all messages
+     */
+    getThread(threadId: string): Promise<MailThread>;
+    /**
+     * List all labels for the authenticated user.
+     *
+     * @returns Array of label objects
+     */
+    listLabels(): Promise<MailLabel[]>;
+    /**
+     * Start watching for new mail by polling at a regular interval.
+     * Emits 'newMail' events with an array of new messages when they arrive.
+     *
+     * Uses Gmail history API to efficiently detect only new messages since the last check.
+     */
+    startWatching(): Promise<void>;
+    /**
+     * Stop watching for new mail.
+     */
+    stopWatching(): void;
+    /** Check for new messages since last history ID using Gmail history API. */
+    private _checkForNewMail;
+}
+declare module '../../feature' {
+    interface AvailableFeatures {
+        googleMail: typeof GoogleMail;
+    }
+}
+export default GoogleMail;
+//# sourceMappingURL=google-mail.d.ts.map

package/dist/node/features/google-mail.d.ts.map

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

package/dist/node/features/google-sheets.d.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+import type { GoogleAuth } from './google-auth.js';
+export type SpreadsheetMeta = {
+    spreadsheetId: string;
+    title: string;
+    locale: string;
+    sheets: SheetInfo[];
+};
+export type SheetInfo = {
+    sheetId: number;
+    title: string;
+    index: number;
+    rowCount: number;
+    columnCount: number;
+};
+export declare const GoogleSheetsStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    lastSpreadsheetId: z.ZodOptional<z.ZodString>;
+    lastSheetName: z.ZodOptional<z.ZodString>;
+    lastRowCount: z.ZodOptional<z.ZodNumber>;
+    lastError: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type GoogleSheetsState = z.infer<typeof GoogleSheetsStateSchema>;
+export declare const GoogleSheetsOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    auth: z.ZodOptional<z.ZodAny>;
+    defaultSpreadsheetId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GoogleSheetsOptions = z.infer<typeof GoogleSheetsOptionsSchema>;
+export declare const GoogleSheetsEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    dataFetched: z.ZodTuple<[z.ZodNumber], null>;
+    error: z.ZodTuple<[z.ZodAny], null>;
+}, z.core.$strip>;
+/**
+ * Google Sheets feature for reading spreadsheet data as JSON, CSV, or raw arrays.
+ *
+ * Depends on the googleAuth feature for authentication. Creates a Sheets v4 API
+ * client lazily and provides convenient methods for reading tabular data.
+ *
+ * @example
+ * ```typescript
+ * const sheets = container.feature('googleSheets', {
+ *   defaultSpreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
+ * })
+ *
+ * // Read as JSON objects (first row = headers)
+ * const data = await sheets.getAsJson('Sheet1')
+ * // => [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+ *
+ * // Read as CSV string
+ * const csv = await sheets.getAsCsv('Revenue')
+ *
+ * // Read a specific range
+ * const values = await sheets.getRange('Sheet1!A1:D10')
+ *
+ * // Save to file
+ * await sheets.saveAsJson('./data/export.json')
+ * ```
+ */
+export declare class GoogleSheets extends Feature<GoogleSheetsState, GoogleSheetsOptions> {
+    static shortcut: "features.googleSheets";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        lastSpreadsheetId: z.ZodOptional<z.ZodString>;
+        lastSheetName: z.ZodOptional<z.ZodString>;
+        lastRowCount: z.ZodOptional<z.ZodNumber>;
+        lastError: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        auth: z.ZodOptional<z.ZodAny>;
+        defaultSpreadsheetId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        dataFetched: z.ZodTuple<[z.ZodNumber], null>;
+        error: z.ZodTuple<[z.ZodAny], null>;
+    }, z.core.$strip>;
+    private _sheets?;
+    get initialState(): GoogleSheetsState;
+    /** Access the google-auth feature lazily. */
+    get auth(): GoogleAuth;
+    /** Get or create the Sheets v4 API client. */
+    private getSheets;
+    /** Resolve spreadsheet ID from argument or default option. */
+    private resolveId;
+    /**
+     * Get spreadsheet metadata including title, locale, and sheet list.
+     *
+     * @param spreadsheetId - The spreadsheet ID (defaults to options.defaultSpreadsheetId)
+     */
+    getSpreadsheet(spreadsheetId?: string): Promise<SpreadsheetMeta>;
+    /**
+     * List all sheets (tabs) in a spreadsheet.
+     *
+     * @param spreadsheetId - The spreadsheet ID
+     */
+    listSheets(spreadsheetId?: string): Promise<SheetInfo[]>;
+    /**
+     * Read a range of values from a sheet.
+     *
+     * @param range - A1 notation range (e.g. "Sheet1!A1:D10" or "Sheet1" for entire sheet)
+     * @param spreadsheetId - The spreadsheet ID
+     * @returns Raw values as a 2D string array
+     */
+    getRange(range: string, spreadsheetId?: string): Promise<string[][]>;
+    /**
+     * Read a sheet as an array of JSON objects.
+     * The first row is treated as headers; subsequent rows become objects keyed by those headers.
+     *
+     * @param sheetName - Name of the sheet tab (if omitted, reads the first sheet)
+     * @param spreadsheetId - The spreadsheet ID
+     */
+    getAsJson<T extends Record<string, any> = Record<string, string>>(sheetName?: string, spreadsheetId?: string): Promise<T[]>;
+    /**
+     * Read a sheet and return it as a CSV string.
+     *
+     * @param sheetName - Name of the sheet tab (if omitted, reads the first sheet)
+     * @param spreadsheetId - The spreadsheet ID
+     */
+    getAsCsv(sheetName?: string, spreadsheetId?: string): Promise<string>;
+    /**
+     * Download sheet data as JSON and save to a local file.
+     *
+     * @param localPath - Local file path (resolved relative to container cwd)
+     * @param sheetName - Sheet tab name (defaults to first sheet)
+     * @param spreadsheetId - The spreadsheet ID
+     * @returns Absolute path of the saved file
+     */
+    saveAsJson(localPath: string, sheetName?: string, spreadsheetId?: string): Promise<string>;
+    /**
+     * Download sheet data as CSV and save to a local file.
+     *
+     * @param localPath - Local file path (resolved relative to container cwd)
+     * @param sheetName - Sheet tab name (defaults to first sheet)
+     * @param spreadsheetId - The spreadsheet ID
+     * @returns Absolute path of the saved file
+     */
+    saveAsCsv(localPath: string, sheetName?: string, spreadsheetId?: string): Promise<string>;
+}
+declare module '../../feature' {
+    interface AvailableFeatures {
+        googleSheets: typeof GoogleSheets;
+    }
+}
+export default GoogleSheets;
+//# sourceMappingURL=google-sheets.d.ts.map

package/dist/node/features/google-sheets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-sheets.d.ts","sourceRoot":"","sources":["../../../src/node/features/google-sheets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,uBAAuB;;;;;;iBASlC,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE,eAAO,MAAM,yBAAyB;;;;;;;iBAIpC,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAE3E,eAAO,MAAM,wBAAwB;;;;;iBAInC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,YAAa,SAAQ,OAAO,CAAC,iBAAiB,EAAE,mBAAmB,CAAC;IAC/E,OAAgB,QAAQ,EAAG,uBAAuB,CAAS;IAC3D,OAAgB,WAAW;;;;;;sBAA0B;IACrD,OAAgB,aAAa;;;;;;;sBAA4B;IACzD,OAAgB,YAAY;;;;;sBAA2B;IAGvD,OAAO,CAAC,OAAO,CAAC,CAAkB;IAElC,IAAa,YAAY,IAAI,iBAAiB,CAE7C;IAED,6CAA6C;IAC7C,IAAI,IAAI,IAAI,UAAU,CAMrB;IAGD,8CAA8C;YAChC,SAAS;IAOvB,8DAA8D;IAC9D,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;IACG,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA2BtE;;;;OAIG;IACG,UAAU,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK9D;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAyB1E;;;;;;OAMG;IACG,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpE,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,CAAC,EAAE,CAAC;IAyBf;;;;;OAKG;IACG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB3E;;;;;;;OAOG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOhG;;;;;;;OAOG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAMhG;AAED,OAAO,QAAQ,eAAe,CAAC;IAC7B,UAAU,iBAAiB;QACzB,YAAY,EAAE,OAAO,YAAY,CAAA;KAClC;CACF;AAED,eAAe,YAAY,CAAA"}

package/dist/node/features/grep.d.ts

@@ -0,0 +1,207 @@
+import { Feature } from '../feature.js';
+export type GrepMatch = {
+    file: string;
+    line: number;
+    column?: number;
+    content: string;
+};
+export type GrepOptions = {
+    /** Pattern to search for (string or regex) */
+    pattern: string;
+    /** Directory or file to search in (defaults to container cwd) */
+    path?: string;
+    /** Glob patterns to include (e.g. '*.ts') */
+    include?: string | string[];
+    /** Glob patterns to exclude (e.g. 'node_modules') */
+    exclude?: string | string[];
+    /** Case insensitive search */
+    ignoreCase?: boolean;
+    /** Treat pattern as a fixed string, not regex */
+    fixedStrings?: boolean;
+    /** Search recursively (default: true) */
+    recursive?: boolean;
+    /** Include hidden files */
+    hidden?: boolean;
+    /** Max number of results to return */
+    maxResults?: number;
+    /** Number of context lines before match */
+    before?: number;
+    /** Number of context lines after match */
+    after?: number;
+    /** Only return filenames, not match details */
+    filesOnly?: boolean;
+    /** Invert match (return lines that don't match) */
+    invert?: boolean;
+    /** Match whole words only */
+    wordMatch?: boolean;
+    /** Additional raw flags to pass to grep/ripgrep */
+    rawFlags?: string[];
+};
+/**
+ * The Grep feature provides utilities for searching file contents using ripgrep (rg) or grep.
+ *
+ * Returns structured results as arrays of `{ file, line, column, content }` objects
+ * with paths relative to the container cwd. Also provides convenience methods for
+ * common search patterns.
+ *
+ * @example
+ * ```typescript
+ * const grep = container.feature('grep')
+ *
+ * // Basic search
+ * const results = await grep.search({ pattern: 'TODO' })
+ * // [{ file: 'src/index.ts', line: 42, column: 5, content: '// TODO: fix this' }, ...]
+ *
+ * // Find all imports of a module
+ * const imports = await grep.imports('lodash')
+ *
+ * // Find function/class/variable definitions
+ * const defs = await grep.definitions('MyClass')
+ *
+ * // Just get filenames containing a pattern
+ * const files = await grep.filesContaining('API_KEY')
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class Grep extends Feature {
+    static shortcut: "features.grep";
+    static stateSchema: import("zod").ZodObject<{
+        enabled: import("zod").ZodDefault<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$loose>;
+    static optionsSchema: import("zod").ZodObject<{
+        name: import("zod").ZodOptional<import("zod").ZodString>;
+        _cacheKey: import("zod").ZodOptional<import("zod").ZodString>;
+        cached: import("zod").ZodOptional<import("zod").ZodBoolean>;
+        enable: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    }, import("zod/v4/core").$strip>;
+    private _hasRipgrep;
+    private _rgPath;
+    private _grepPath;
+    /** Whether ripgrep (rg) is available on this system */
+    get hasRipgrep(): boolean;
+    /** Resolved path to the rg binary */
+    get rgPath(): string;
+    /** Resolved path to the grep binary */
+    get grepPath(): string;
+    /**
+     * Search for a pattern in files and return structured results.
+     *
+     * @param {GrepOptions} options - Search options
+     * @returns {Promise<GrepMatch[]>} Array of match objects with relative file paths
+     *
+     * @example
+     * ```typescript
+     * // Search for a pattern in TypeScript files
+     * const results = await grep.search({
+     *   pattern: 'useState',
+     *   include: '*.tsx',
+     *   exclude: 'node_modules'
+     * })
+     *
+     * // Case insensitive search with context
+     * const results = await grep.search({
+     *   pattern: 'error',
+     *   ignoreCase: true,
+     *   before: 2,
+     *   after: 2
+     * })
+     * ```
+     */
+    search(options: GrepOptions): Promise<GrepMatch[]>;
+    /**
+     * Find files containing a pattern. Returns just the relative file paths.
+     *
+     * @param {string} pattern - The pattern to search for
+     * @param {Omit<GrepOptions, 'pattern' | 'filesOnly'>} [options] - Additional search options
+     * @returns {Promise<string[]>} Array of relative file paths
+     *
+     * @example
+     * ```typescript
+     * const files = await grep.filesContaining('TODO')
+     * // ['src/index.ts', 'src/utils.ts']
+     * ```
+     */
+    filesContaining(pattern: string, options?: Omit<GrepOptions, 'pattern' | 'filesOnly'>): Promise<string[]>;
+    /**
+     * Find import/require statements for a module or path.
+     *
+     * @param {string} moduleOrPath - The module name or path to search for in imports
+     * @param {Omit<GrepOptions, 'pattern'>} [options] - Additional search options
+     * @returns {Promise<GrepMatch[]>} Array of matches
+     *
+     * @example
+     * ```typescript
+     * const lodashImports = await grep.imports('lodash')
+     * const localImports = await grep.imports('./utils')
+     * ```
+     */
+    imports(moduleOrPath: string, options?: Omit<GrepOptions, 'pattern'>): Promise<GrepMatch[]>;
+    /**
+     * Find function, class, type, or variable definitions matching a name.
+     *
+     * @param {string} name - The identifier name to search for definitions of
+     * @param {Omit<GrepOptions, 'pattern'>} [options] - Additional search options
+     * @returns {Promise<GrepMatch[]>} Array of matches
+     *
+     * @example
+     * ```typescript
+     * const defs = await grep.definitions('MyComponent')
+     * const classDefs = await grep.definitions('UserService')
+     * ```
+     */
+    definitions(name: string, options?: Omit<GrepOptions, 'pattern'>): Promise<GrepMatch[]>;
+    /**
+     * Find TODO, FIXME, HACK, and XXX comments.
+     *
+     * @param {Omit<GrepOptions, 'pattern'>} [options] - Additional search options
+     * @returns {Promise<GrepMatch[]>} Array of matches
+     *
+     * @example
+     * ```typescript
+     * const todos = await grep.todos()
+     * const fixmes = await grep.todos({ include: '*.ts' })
+     * ```
+     */
+    todos(options?: Omit<GrepOptions, 'pattern'>): Promise<GrepMatch[]>;
+    /**
+     * Count the number of matches for a pattern.
+     *
+     * @param {string} pattern - The pattern to count
+     * @param {Omit<GrepOptions, 'pattern'>} [options] - Additional search options
+     * @returns {Promise<number>} Total number of matching lines
+     *
+     * @example
+     * ```typescript
+     * const count = await grep.count('console.log')
+     * console.log(`Found ${count} console.log statements`)
+     * ```
+     */
+    count(pattern: string, options?: Omit<GrepOptions, 'pattern'>): Promise<number>;
+    /**
+     * Search and replace across files. Returns the list of files that would be affected.
+     * Does NOT modify files — use the returned file list to do the replacement yourself.
+     *
+     * @param {string} pattern - The pattern to search for
+     * @param {Omit<GrepOptions, 'pattern'>} [options] - Additional search options
+     * @returns {Promise<{ file: string, matches: GrepMatch[] }[]>} Array of files with their matches, grouped by file
+     *
+     * @example
+     * ```typescript
+     * const affected = await grep.findForReplace('oldFunctionName')
+     * // [{ file: 'src/a.ts', matches: [...] }, { file: 'src/b.ts', matches: [...] }]
+     * ```
+     */
+    findForReplace(pattern: string, options?: Omit<GrepOptions, 'pattern'>): Promise<{
+        file: string;
+        matches: GrepMatch[];
+    }[]>;
+    /** Build the grep/rg command from options */
+    private buildCommand;
+    /** Parse raw grep/rg output into structured results */
+    private parseResults;
+    /** Make a path relative to cwd */
+    private relativize;
+}
+export default Grep;
+//# sourceMappingURL=grep.d.ts.map

package/dist/node/features/grep.d.ts.map

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