@soederpop/luca 0.0.32 → 0.0.34

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

@@ -30,6 +30,21 @@ const buffer = fs.readFile('image.png', null)
 
 
 
+### readFileSync
+
+Synchronously reads a file and returns its contents as a string. added this method because AI Assistants are understandly confused by this deviation from 2000's era node style
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | Parameter path |
+| `encoding` | `BufferEncoding | null` |  | Parameter encoding |
+
+**Returns:** `string | Buffer`
+
+
+
 ### readFileAsync
 
 Asynchronously reads a file and returns its contents as a string.
@@ -60,7 +75,7 @@ Synchronously reads and parses a JSON file.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path to the JSON file |
 
-**Returns:** `void`
+**Returns:** `any`
 
 ```ts
 const config = fs.readJson('config.json')
@@ -69,6 +84,20 @@ console.log(config.version)
 
 
 
+### readJsonSync
+
+Read and parse a JSON file synchronously
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | Parameter path |
+
+**Returns:** `any`
+
+
+
 ### readJsonAsync
 
 Asynchronously reads and parses a JSON file.
@@ -79,7 +108,7 @@ Asynchronously reads and parses a JSON file.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path to the JSON file |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 ```ts
 const config = await fs.readJsonAsync('config.json')
@@ -98,7 +127,7 @@ Synchronously reads the contents of a directory.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The directory path relative to the container's working directory |
 
-**Returns:** `void`
+**Returns:** `string[]`
 
 ```ts
 const entries = fs.readdirSync('src')
@@ -117,7 +146,7 @@ Asynchronously reads the contents of a directory.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The directory path relative to the container's working directory |
 
-**Returns:** `void`
+**Returns:** `Promise<string[]>`
 
 ```ts
 const entries = await fs.readdir('src')
@@ -157,7 +186,7 @@ Asynchronously writes content to a file.
 | `path` | `string` | ✓ | The file path where content should be written |
 | `content` | `Buffer | string` | ✓ | The content to write to the file |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.writeFileAsync('output.txt', 'Hello World')
@@ -198,7 +227,7 @@ Asynchronously writes an object to a file as JSON.
 | `data` | `any` | ✓ | The data to serialize as JSON |
 | `indent` | `number` |  | The number of spaces to use for indentation |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.writeJsonAsync('config.json', { version: '1.0.0', debug: false })
@@ -236,7 +265,7 @@ Asynchronously appends content to a file.
 | `path` | `string` | ✓ | The file path to append to |
 | `content` | `Buffer | string` | ✓ | The content to append |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.appendFileAsync('log.txt', 'New line\n')
@@ -256,7 +285,7 @@ Synchronously ensures a file exists with the specified content, creating directo
 | `content` | `string` | ✓ | The content to write to the file |
 | `overwrite` | `any` |  | Whether to overwrite the file if it already exists |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 fs.ensureFile('logs/app.log', '', false)
@@ -276,7 +305,7 @@ Asynchronously ensures a file exists with the specified content, creating direct
 | `content` | `string` | ✓ | The content to write to the file |
 | `overwrite` | `any` |  | Whether to overwrite the file if it already exists |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 await fs.ensureFileAsync('config/settings.json', '{}', true)
@@ -294,7 +323,7 @@ Synchronously ensures a directory exists, creating parent directories as needed.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The directory path to create |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 fs.ensureFolder('logs/debug')
@@ -312,7 +341,7 @@ Asynchronously ensures a directory exists, creating parent directories as needed
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The directory path to create |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 await fs.ensureFolderAsync('logs/debug')
@@ -330,7 +359,7 @@ Alias for ensureFolder. Synchronously creates a directory and all parent directo
 |------|------|----------|-------------|
 | `folder` | `string` | ✓ | The directory path to create |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 fs.mkdirp('deep/nested/path')
@@ -388,7 +417,7 @@ Asynchronously checks if a file or directory exists.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path to check for existence |
 
-**Returns:** `void`
+**Returns:** `Promise<boolean>`
 
 ```ts
 if (await fs.existsAsync('config.json')) {
@@ -398,6 +427,34 @@ if (await fs.existsAsync('config.json')) {
 
 
 
+### isSymlink
+
+Checks if a path is a symbolic link.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | The path to check |
+
+**Returns:** `boolean`
+
+
+
+### realpath
+
+Resolves a symlink to its real path. Returns the resolved path as-is if not a symlink.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | The path to resolve |
+
+**Returns:** `string`
+
+
+
 ### stat
 
 Synchronously returns the stat object for a file or directory.
@@ -408,7 +465,7 @@ Synchronously returns the stat object for a file or directory.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path to stat |
 
-**Returns:** `void`
+**Returns:** `Stats`
 
 ```ts
 const info = fs.stat('package.json')
@@ -427,7 +484,7 @@ Asynchronously returns the stat object for a file or directory.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path to stat |
 
-**Returns:** `void`
+**Returns:** `Promise<Stats>`
 
 ```ts
 const info = await fs.statAsync('package.json')
@@ -544,7 +601,7 @@ Asynchronously removes a file.
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | The path of the file to remove |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.rm('temp/cache.tmp')
@@ -580,7 +637,7 @@ Asynchronously removes a directory and all its contents.
 |------|------|----------|-------------|
 | `dirPath` | `string` | ✓ | The path of the directory to remove |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.rmdir('temp/cache')
@@ -633,7 +690,7 @@ Asynchronously copies a file or directory. Auto-detects whether the source is a
 |----------|------|-------------|
 | `overwrite` | `any` | Whether to overwrite existing files at the destination |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.copyAsync('src/config.json', 'backup/config.json')
@@ -673,7 +730,7 @@ Asynchronously moves (renames) a file or directory. Falls back to copy + delete
 | `src` | `string` | ✓ | The source path to move from |
 | `dest` | `string` | ✓ | The destination path to move to |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 ```ts
 await fs.moveAsync('temp/draft.txt', 'final/document.txt')
@@ -703,7 +760,7 @@ Recursively walks a directory and returns arrays of file and directory paths. By
 | `include` | `string | string[]` | ] - Glob patterns to include (only matching paths are returned) |
 | `relative` | `boolean` | When true, returned paths are relative to `baseDir` instead of absolute. |
 
-**Returns:** `void`
+**Returns:** `{ directories: string[], files: string[] }`
 
 ```ts
 const result = fs.walk('src', { files: true, directories: false })
@@ -734,7 +791,7 @@ Asynchronously and recursively walks a directory and returns arrays of file and
 | `include` | `string | string[]` | ] - Glob patterns to include (only matching paths are returned) |
 | `relative` | `boolean` | When true, returned paths are relative to `baseDir` instead of absolute. |
 
-**Returns:** `void`
+**Returns:** `Promise<{ directories: string[], files: string[] }>`
 
 ```ts
 const result = await fs.walkAsync('src', { exclude: ['node_modules'] })

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

@@ -34,7 +34,7 @@ Lists files in the Git repository using git ls-files command. This method provid
 | `exclude` | `string | string[]` | Patterns to exclude from results |
 | `baseDir` | `string` | Base directory to list files from |
 
-**Returns:** `void`
+**Returns:** `Promise<string[]>`
 
 ```ts
 // Get all tracked files
@@ -62,7 +62,7 @@ Gets the latest commits from the repository. Returns an array of commit objects
 |------|------|----------|-------------|
 | `numberOfChanges` | `number` |  | The number of recent commits to return |
 
-**Returns:** `void`
+**Returns:** `Promise<Array<{ title: string, message: string, author: string }>>`
 
 ```ts
 const changes = await git.getLatestChanges(5)
@@ -83,7 +83,7 @@ Gets a lightweight commit log for one or more files. Returns the SHA and message
 |------|------|----------|-------------|
 | `files` | `string[]` | ✓ | File paths (absolute or relative to container.cwd) |
 
-**Returns:** `void`
+**Returns:** `Array<{ sha: string, message: string }>`
 
 ```ts
 const log = git.fileLog('package.json')
@@ -107,7 +107,7 @@ Gets the diff for a file between two refs. By default compares from the current
 | `compareTo` | `string` | ✓ | The target ref (commit SHA, branch, tag) to compare to |
 | `compareFrom` | `string` |  | The base ref to compare from (defaults to current HEAD) |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Diff package.json between HEAD and a specific commit
@@ -144,6 +144,31 @@ git.displayDiff('src/index.ts', 'abc1234')
 
 
 
+### extractFolder
+
+Extracts a folder (or entire repo) from a remote GitHub repository without cloning. Downloads the repo as a tarball and extracts only the specified subfolder, similar to how degit works. No .git history is included — just the files. Supports shorthand (`user/repo/path`), branch refs (`user/repo/path#branch`), and full GitHub URLs (`https://github.com/user/repo/tree/branch/path`).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ source, destination, branch }` | `{ source: string, destination: string, branch?: string }` | ✓ | Parameter { source, destination, branch } |
+
+**Returns:** `Promise<{ files: string[], source: { user: string, repo: string, ref: string, subdir: string`
+
+```ts
+// Extract a subfolder
+await git.extractFolder({ source: 'soederpop/luca/src/assistants', destination: './my-assistants' })
+
+// Specific branch
+await git.extractFolder({ source: 'sveltejs/template', destination: './my-app', branch: 'main' })
+
+// Full GitHub URL
+await git.extractFolder({ source: 'https://github.com/user/repo/tree/main/examples', destination: './examples' })
+```
+
+
+
 ### getChangeHistoryForFiles
 
 Gets the commit history for a set of files or glob patterns. Accepts absolute paths, relative paths (resolved from container.cwd), or glob patterns. Returns commits that touched any of the matched files, with each entry noting which of your queried files were in that commit.
@@ -154,7 +179,7 @@ Gets the commit history for a set of files or glob patterns. Accepts absolute pa
 |------|------|----------|-------------|
 | `paths` | `string[]` | ✓ | File paths or glob patterns to get history for |
 
-**Returns:** `void`
+**Returns:** `Array<{ sha: string, message: string, longMessage: string, filesMatched: string[] }>`
 
 ```ts
 const history = git.getChangeHistoryForFiles('src/container.ts', 'src/helper.ts')
@@ -168,11 +193,11 @@ const history = git.getChangeHistoryForFiles('src/node/features/*.ts')
 | Property | Type | Description |
 |----------|------|-------------|
 | `gitPath` | `string` | Resolve the git binary path via `which`, caching the result. |
-| `branch` | `any` | Gets the current Git branch name. |
-| `sha` | `any` | Gets the current Git commit SHA hash. |
-| `isRepo` | `any` | Checks if the current directory is within a Git repository. |
-| `isRepoRoot` | `any` | Checks if the current working directory is the root of the Git repository. |
-| `repoRoot` | `any` | Gets the absolute path to the Git repository root directory. This method caches the repository root path for performance. It searches upward from the current directory to find the .git directory. |
+| `branch` | `string | null` | Gets the current Git branch name. |
+| `sha` | `string | null` | Gets the current Git commit SHA hash. |
+| `isRepo` | `boolean` | Checks if the current directory is within a Git repository. |
+| `isRepoRoot` | `boolean` | Checks if the current working directory is the root of the Git repository. |
+| `repoRoot` | `string | null` | Gets the absolute path to the Git repository root directory. This method caches the repository root path for performance. It searches upward from the current directory to find the .git directory. |
 
 ## State (Zod v4 schema)
 
@@ -265,6 +290,21 @@ git.displayDiff('src/index.ts', 'abc1234')
 
 
 
+**extractFolder**
+
+```ts
+// Extract a subfolder
+await git.extractFolder({ source: 'soederpop/luca/src/assistants', destination: './my-assistants' })
+
+// Specific branch
+await git.extractFolder({ source: 'sveltejs/template', destination: './my-app', branch: 'main' })
+
+// Full GitHub URL
+await git.extractFolder({ source: 'https://github.com/user/repo/tree/main/examples', destination: './examples' })
+```
+
+
+
 **getChangeHistoryForFiles**
 
 ```ts

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

@@ -6,6 +6,8 @@ Google Calendar feature for listing calendars and reading events. Depends on the
 
 ```ts
 container.feature('googleCalendar', {
+  // An authorized instance of the googleAuth feature
+  auth,
   // Default calendar ID (default: "primary")
   defaultCalendarId,
   // Default timezone for event queries (e.g. "America/Chicago")
@@ -17,6 +19,7 @@ container.feature('googleCalendar', {
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
 | `defaultCalendarId` | `string` | Default calendar ID (default: "primary") |
 | `timeZone` | `string` | Default timezone for event queries (e.g. "America/Chicago") |
 

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

@@ -5,9 +5,18 @@ Google Docs feature for reading documents and converting them to Markdown. Depen
 ## Usage
 
 ```ts
-container.feature('googleDocs')
+container.feature('googleDocs', {
+  // An authorized instance of the googleAuth feature
+  auth,
+})
 ```
 
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
+
 ## Methods
 
 ### getDocument

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

@@ -6,6 +6,8 @@ Google Drive feature for listing, searching, browsing, and downloading files. De
 
 ```ts
 container.feature('googleDrive', {
+  // An authorized instance of the googleAuth feature
+  auth,
   // Default corpus for file queries (default: user)
   defaultCorpora,
   // Default number of results per page (default: 100)
@@ -17,6 +19,7 @@ container.feature('googleDrive', {
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
 | `defaultCorpora` | `string` | Default corpus for file queries (default: user) |
 | `pageSize` | `number` | Default number of results per page (default: 100) |
 

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

@@ -6,6 +6,8 @@ Google Sheets feature for reading spreadsheet data as JSON, CSV, or raw arrays.
 
 ```ts
 container.feature('googleSheets', {
+  // An authorized instance of the googleAuth feature
+  auth,
   // Default spreadsheet ID for operations
   defaultSpreadsheetId,
 })
@@ -15,6 +17,7 @@ container.feature('googleSheets', {
 
 | Property | Type | Description |
 |----------|------|-------------|
+| `auth` | `any` | An authorized instance of the googleAuth feature |
 | `defaultSpreadsheetId` | `string` | Default spreadsheet ID for operations |
 
 ## Methods