luca 3.0.0 → 3.1.0

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

@@ -1,214 +0,0 @@
-# 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

@@ -1,194 +0,0 @@
-# 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

@@ -1,292 +0,0 @@
-# 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: [...] }]
-```
-