luca 2.0.0 → 3.0.0

package/docs/apis/features/node/google-mail.md

@@ -0,0 +1,214 @@
+# GoogleMail (features.googleMail)
+
+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.
+
+## Usage
+
+```ts
+container.feature('googleMail', {
+  // An authorized instance of the googleAuth feature
+  auth,
+  // Gmail user ID (default: "me")
+  userId,
+  // Polling interval in ms for watching new mail (default: 30000)
+  pollInterval,
+  // Default message format when fetching (default: "full")
+  format,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+| `userId` | `string` | Gmail user ID (default: "me") |
+| `pollInterval` | `number` | Polling interval in ms for watching new mail (default: 30000) |
+| `format` | `string` | Default message format when fetching (default: "full") |
+
+## Methods
+
+### search
+
+Search for messages using Gmail query syntax and/or structured filters.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `SearchMailOptions` |  | Search filters including query, from, to, subject, date ranges |
+
+`SearchMailOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `query` | `string` |  |
+| `from` | `string` |  |
+| `to` | `string` |  |
+| `subject` | `string` |  |
+| `after` | `string` |  |
+| `before` | `string` |  |
+| `hasAttachment` | `boolean` |  |
+| `label` | `string` |  |
+| `isUnread` | `boolean` |  |
+| `maxResults` | `number` |  |
+| `pageToken` | `string` |  |
+
+**Returns:** `Promise<MailMessageList>`
+
+
+
+### getMessage
+
+Get a single message by ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `messageId` | `string` | ✓ | The message ID |
+| `format` | `'full' | 'metadata' | 'minimal' | 'raw'` |  | Message format (defaults to options.format or 'full') |
+
+**Returns:** `Promise<MailMessage>`
+
+
+
+### getThread
+
+Get a full thread with all its messages.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `threadId` | `string` | ✓ | The thread ID |
+
+**Returns:** `Promise<MailThread>`
+
+
+
+### listLabels
+
+List all labels for the authenticated user.
+
+**Returns:** `Promise<MailLabel[]>`
+
+
+
+### startWatching
+
+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.
+
+**Returns:** `Promise<void>`
+
+
+
+### stopWatching
+
+Stop watching for new mail.
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+| `userId` | `string` | Default user ID from options or 'me'. |
+| `defaultFormat` | `'full' | 'metadata' | 'minimal' | 'raw'` | Default message format from options or 'full'. |
+| `pollInterval` | `number` | Polling interval from options or 30 seconds. |
+
+## Events (Zod v4 schema)
+
+### messagesFetched
+
+Messages were fetched from Gmail
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Number of messages returned |
+
+
+
+### error
+
+Gmail API error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### watchStarted
+
+Mail watching has started
+
+
+
+### watchStopped
+
+Mail watching has stopped
+
+
+
+### newMail
+
+New mail arrived (emitted by watch)
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `array` | Array of new MailMessage objects |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastQuery` | `string` | Last search query used |
+| `lastResultCount` | `number` | Number of messages returned in last search |
+| `lastError` | `string` | Last Gmail API error message |
+| `watchExpiration` | `string` | ISO timestamp when the current watch expires |
+
+## Examples
+
+**features.googleMail**
+
+```ts
+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()
+```
+

package/docs/apis/features/node/google-sheets.md

@@ -0,0 +1,194 @@
+# GoogleSheets (features.googleSheets)
+
+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.
+
+## Usage
+
+```ts
+container.feature('googleSheets', {
+  // An authorized instance of the googleAuth feature
+  auth,
+  // Default spreadsheet ID for operations
+  defaultSpreadsheetId,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+| `defaultSpreadsheetId` | `string` | Default spreadsheet ID for operations |
+
+## Methods
+
+### getSpreadsheet
+
+Get spreadsheet metadata including title, locale, and sheet list.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `spreadsheetId` | `string` |  | The spreadsheet ID (defaults to options.defaultSpreadsheetId) |
+
+**Returns:** `Promise<SpreadsheetMeta>`
+
+
+
+### listSheets
+
+List all sheets (tabs) in a spreadsheet.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<SheetInfo[]>`
+
+
+
+### getRange
+
+Read a range of values from a sheet.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `range` | `string` | ✓ | A1 notation range (e.g. "Sheet1!A1:D10" or "Sheet1" for entire sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string[][]>`
+
+
+
+### getAsJson
+
+Read a sheet as an array of JSON objects. The first row is treated as headers; subsequent rows become objects keyed by those headers.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sheetName` | `string` |  | Name of the sheet tab (if omitted, reads the first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<T[]>`
+
+
+
+### getAsCsv
+
+Read a sheet and return it as a CSV string.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `sheetName` | `string` |  | Name of the sheet tab (if omitted, reads the first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### saveAsJson
+
+Download sheet data as JSON and save to a local file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+| `sheetName` | `string` |  | Sheet tab name (defaults to first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+### saveAsCsv
+
+Download sheet data as CSV and save to a local file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `localPath` | `string` | ✓ | Local file path (resolved relative to container cwd) |
+| `sheetName` | `string` |  | Sheet tab name (defaults to first sheet) |
+| `spreadsheetId` | `string` |  | The spreadsheet ID |
+
+**Returns:** `Promise<string>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `GoogleAuth` | Access the google-auth feature lazily. |
+
+## Events (Zod v4 schema)
+
+### error
+
+Sheets API error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### dataFetched
+
+Sheet data was fetched
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Number of rows |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastSpreadsheetId` | `string` | Last spreadsheet ID accessed |
+| `lastSheetName` | `string` | Last sheet/tab name accessed |
+| `lastRowCount` | `number` | Number of rows returned in last read |
+| `lastError` | `string` | Last Sheets API error message |
+
+## Examples
+
+**features.googleSheets**
+
+```ts
+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')
+```
+

package/docs/apis/features/node/grep.md

@@ -0,0 +1,292 @@
+# Grep (features.grep)
+
+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.
+
+## Usage
+
+```ts
+container.feature('grep')
+```
+
+## Methods
+
+### search
+
+Search for a pattern in files and return structured results.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `GrepOptions` | ✓ | Search options |
+
+`GrepOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pattern` | `string` | Pattern to search for (string or regex) |
+| `path` | `string` | Directory or file to search in (defaults to container cwd) |
+| `include` | `string | string[]` | Glob patterns to include (e.g. '*.ts') |
+| `exclude` | `string | string[]` | Glob patterns to exclude (e.g. 'node_modules') |
+| `ignoreCase` | `boolean` | Case insensitive search |
+| `fixedStrings` | `boolean` | Treat pattern as a fixed string, not regex |
+| `recursive` | `boolean` | Search recursively (default: true) |
+| `hidden` | `boolean` | Include hidden files |
+| `maxResults` | `number` | Max number of results to return |
+| `before` | `number` | Number of context lines before match |
+| `after` | `number` | Number of context lines after match |
+| `filesOnly` | `boolean` | Only return filenames, not match details |
+| `invert` | `boolean` | Invert match (return lines that don't match) |
+| `wordMatch` | `boolean` | Match whole words only |
+| `rawFlags` | `string[]` | Additional raw flags to pass to grep/ripgrep |
+
+**Returns:** `Promise<GrepMatch[]>`
+
+```ts
+// 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
+})
+```
+
+
+
+### filesContaining
+
+Find files containing a pattern. Returns just the relative file paths.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pattern` | `string` | ✓ | The pattern to search for |
+| `options` | `Omit<GrepOptions, 'pattern' | 'filesOnly'>` |  | Additional search options |
+
+**Returns:** `Promise<string[]>`
+
+```ts
+const files = await grep.filesContaining('TODO')
+// ['src/index.ts', 'src/utils.ts']
+```
+
+
+
+### imports
+
+Find import/require statements for a module or path.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `moduleOrPath` | `string` | ✓ | The module name or path to search for in imports |
+| `options` | `Omit<GrepOptions, 'pattern'>` |  | Additional search options |
+
+**Returns:** `Promise<GrepMatch[]>`
+
+```ts
+const lodashImports = await grep.imports('lodash')
+const localImports = await grep.imports('./utils')
+```
+
+
+
+### definitions
+
+Find function, class, type, or variable definitions matching a name.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The identifier name to search for definitions of |
+| `options` | `Omit<GrepOptions, 'pattern'>` |  | Additional search options |
+
+**Returns:** `Promise<GrepMatch[]>`
+
+```ts
+const defs = await grep.definitions('MyComponent')
+const classDefs = await grep.definitions('UserService')
+```
+
+
+
+### todos
+
+Find TODO, FIXME, HACK, and XXX comments.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `Omit<GrepOptions, 'pattern'>` |  | Additional search options |
+
+**Returns:** `Promise<GrepMatch[]>`
+
+```ts
+const todos = await grep.todos()
+const fixmes = await grep.todos({ include: '*.ts' })
+```
+
+
+
+### count
+
+Count the number of matches for a pattern.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pattern` | `string` | ✓ | The pattern to count |
+| `options` | `Omit<GrepOptions, 'pattern'>` |  | Additional search options |
+
+**Returns:** `Promise<number>`
+
+```ts
+const count = await grep.count('console.log')
+console.log(`Found ${count} console.log statements`)
+```
+
+
+
+### findForReplace
+
+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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pattern` | `string` | ✓ | The pattern to search for |
+| `options` | `Omit<GrepOptions, 'pattern'>` |  | Additional search options |
+
+**Returns:** `Promise<{ file: string, matches: GrepMatch[] }[]>`
+
+```ts
+const affected = await grep.findForReplace('oldFunctionName')
+// [{ file: 'src/a.ts', matches: [...] }, { file: 'src/b.ts', matches: [...] }]
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hasRipgrep` | `boolean` | Whether ripgrep (rg) is available on this system |
+| `rgPath` | `string` | Resolved path to the rg binary |
+| `grepPath` | `string` | Resolved path to the grep binary |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.grep**
+
+```ts
+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')
+```
+
+
+
+**search**
+
+```ts
+// 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
+})
+```
+
+
+
+**filesContaining**
+
+```ts
+const files = await grep.filesContaining('TODO')
+// ['src/index.ts', 'src/utils.ts']
+```
+
+
+
+**imports**
+
+```ts
+const lodashImports = await grep.imports('lodash')
+const localImports = await grep.imports('./utils')
+```
+
+
+
+**definitions**
+
+```ts
+const defs = await grep.definitions('MyComponent')
+const classDefs = await grep.definitions('UserService')
+```
+
+
+
+**todos**
+
+```ts
+const todos = await grep.todos()
+const fixmes = await grep.todos({ include: '*.ts' })
+```
+
+
+
+**count**
+
+```ts
+const count = await grep.count('console.log')
+console.log(`Found ${count} console.log statements`)
+```
+
+
+
+**findForReplace**
+
+```ts
+const affected = await grep.findForReplace('oldFunctionName')
+// [{ file: 'src/a.ts', matches: [...] }, { file: 'src/b.ts', matches: [...] }]
+```
+