@soederpop/luca 0.0.2

package/docs/examples/fs.md

@@ -0,0 +1,83 @@
+---
+title: "fs"
+tags: [fs, filesystem, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# fs
+
+File system utilities for reading, writing, checking, and walking files and directories.
+
+## Overview
+
+The `fs` feature is a core feature, meaning it is auto-enabled on every container. You can access it directly as a global or via `container.feature('fs')`. It provides synchronous and asynchronous methods for common filesystem operations. All paths are resolved relative to the container's working directory.
+
+## Reading Files
+
+Use `readFile()` to read a file as a string. This is the simplest way to get file contents.
+
+```ts
+const content = fs.readFile('README.md')
+console.log('README.md length:', content.length, 'characters')
+console.log('First line:', content.split('\n')[0])
+```
+
+The returned value is always a string, ready for processing.
+
+## Reading JSON
+
+Use `readJson()` to read and parse a JSON file in one step. No need for manual `JSON.parse()`.
+
+```ts
+const pkg = fs.readJson('package.json')
+console.log('Package name:', pkg.name)
+console.log('Version:', pkg.version)
+console.log('Dependencies:', Object.keys(pkg.dependencies || {}).length, 'packages')
+```
+
+This is especially handy for configuration files and manifests.
+
+## Checking Existence
+
+Use `exists()` to check whether a file or directory is present before operating on it.
+
+```ts
+console.log('README.md exists:', fs.exists('README.md'))
+console.log('package.json exists:', fs.exists('package.json'))
+console.log('nonexistent.txt exists:', fs.exists('nonexistent.txt'))
+console.log('src/ exists:', fs.exists('src'))
+```
+
+Returns a simple boolean. There is also an `existsAsync()` variant.
+
+## Walking a Directory
+
+Use `walk()` to recursively list all files under a directory tree. You can filter to just files or just directories.
+
+```ts
+const result = fs.walk('src', { files: true, directories: false, exclude: ['node_modules'] })
+console.log('Total files in src/:', result.files.length)
+console.log('First 5 files:')
+result.files.slice(0, 5).forEach(f => console.log(' ', f))
+```
+
+Walk returns an object with `files` and `directories` arrays of relative paths.
+
+## Finding Files Upward
+
+Use `findUp()` to search for a file by walking up the directory tree from the current working directory. This is useful for locating project root markers.
+
+```ts
+const tsconfig = fs.findUp('tsconfig.json')
+console.log('tsconfig.json found at:', tsconfig)
+
+const packageJson = fs.findUp('package.json')
+console.log('package.json found at:', packageJson)
+```
+
+Returns the absolute path if found, or `null` if the file is not in any ancestor directory.
+
+## Summary
+
+This demo covered reading files as strings and JSON, checking existence, recursively walking directories, and searching upward for project configuration files. These are the bread-and-butter operations for any script that needs to interact with the filesystem.

package/docs/examples/git.md

@@ -0,0 +1,85 @@
+---
+title: "git"
+tags: [git, version-control, core]
+lastTested: null
+lastTestPassed: null
+---
+
+# git
+
+Git repository operations including branch info, commit history, and file listing.
+
+## Overview
+
+The `git` feature is a core feature, auto-enabled on every container. You can access it directly as a global or via `container.feature('git')`. It provides getters for quick repo metadata and methods for querying commit history and tracked files. All operations use the repository that contains the container's working directory.
+
+## Repository Info
+
+The basic getters give you quick access to the current repository state without any arguments.
+
+```ts
+console.log('Is a git repo:', git.isRepo)
+console.log('Repo root:', git.repoRoot)
+console.log('Current branch:', git.branch)
+console.log('Current SHA:', git.sha)
+```
+
+These are synchronous getters, so you can use them inline anywhere.
+
+## Listing Tracked Files
+
+Use `lsFiles()` to list files tracked by git. This wraps `git ls-files` with structured options.
+
+```ts
+const files = await git.lsFiles()
+console.log('Total tracked files:', files.length)
+console.log('First 5 files:')
+files.slice(0, 5).forEach(f => console.log(' ', f))
+```
+
+You can filter for modified, deleted, or untracked files by passing options.
+
+## Filtered File Listing
+
+Pass options to `lsFiles()` to narrow down the results by file status or pattern.
+
+```ts
+const tsFiles = await git.lsFiles({ include: '*.ts' })
+console.log('Tracked .ts files:', tsFiles.length)
+
+const srcFiles = await git.lsFiles({ baseDir: 'src' })
+console.log('Files in src/:', srcFiles.length)
+```
+
+The `include`, `exclude`, and `baseDir` options let you scope the listing precisely.
+
+## Latest Commits
+
+Use `getLatestChanges()` to retrieve recent commit metadata. Each entry has a `title`, `message`, and `author`.
+
+```ts
+const changes = await git.getLatestChanges(3)
+changes.forEach((c, i) => {
+  console.log(`${i + 1}. [${c.author}] ${c.title}`)
+})
+```
+
+This is useful for generating changelogs, displaying recent activity, or auditing history.
+
+## File History
+
+Use `fileLog()` to see the commit history for a specific file.
+
+```ts
+const log = git.fileLog('package.json')
+console.log('Commits touching package.json:', log.length)
+log.slice(0, 3).forEach(entry => {
+  console.log(`  ${entry.sha.slice(0, 8)} ${entry.message}`)
+})
+```
+
+Each entry contains the commit `sha` and `message`. This is a synchronous method.
+
+## Summary
+
+This demo covered checking repository status, listing tracked files with filters, viewing recent commit history, and inspecting per-file commit logs. These tools give scripts full visibility into the git state of a project.

package/docs/examples/google-auth.md

@@ -0,0 +1,88 @@
+---
+title: "Google Auth"
+tags: [googleAuth, google, oauth2, authentication, service-account]
+lastTested: null
+lastTestPassed: null
+---
+
+# googleAuth
+
+Google authentication feature supporting OAuth2 browser flow and service account auth. Handles the complete OAuth2 lifecycle including token refresh and secure storage via diskCache.
+
+## Overview
+
+Use the `googleAuth` feature to authenticate with Google APIs. It supports two modes: OAuth2 (opens a browser for user consent) and service account (non-interactive, uses a JSON key file). Other Google features (drive, sheets, calendar, docs) depend on this feature automatically.
+
+Requires either `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables for OAuth2, or a service account key file.
+
+## Enabling the Feature
+
+```ts
+const auth = container.feature('googleAuth')
+console.log('Auth mode:', auth.authMode)
+console.log('Authenticated:', auth.isAuthenticated)
+```
+
+The feature reads `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` from the environment automatically. You can also pass `clientId` and `clientSecret` as options.
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('googleAuth')
+console.log(info)
+```
+
+## OAuth2 Authorization Flow
+
+The `authorize()` method starts the full OAuth2 browser flow: it spins up a local callback server, opens the consent page, exchanges the code for tokens, and caches the refresh token.
+
+```ts skip
+const auth = container.feature('googleAuth', {
+  scopes: ['https://www.googleapis.com/auth/drive.readonly']
+})
+await auth.authorize()
+console.log('Authenticated:', auth.isAuthenticated)
+console.log('Scopes:', auth.state.scopes)
+```
+
+When running with valid credentials, this opens a browser to Google's consent page. After approval, tokens are stored in diskCache and automatically refreshed on expiry.
+
+## Service Account Authentication
+
+For server-to-server auth without a browser, use a service account JSON key file.
+
+```ts skip
+const auth = container.feature('googleAuth', {
+  mode: 'service-account',
+  serviceAccountKeyPath: '/path/to/service-account-key.json',
+  scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly']
+})
+await auth.authenticateServiceAccount()
+console.log('Service account email:', auth.state.email)
+```
+
+Service accounts are ideal for automation, CI/CD, and background services that need Google API access without user interaction.
+
+## Token Management
+
+Tokens are cached automatically and restored on subsequent runs. You can also revoke credentials.
+
+```ts skip
+// Attempt to restore from cache (called automatically)
+const restored = await auth.tryRestoreTokens()
+console.log('Restored from cache:', restored)
+
+// Get the auth client for passing to Google API constructors
+const client = await auth.getAuthClient()
+console.log('Auth client ready')
+
+// Revoke and clear cached tokens
+await auth.revoke()
+console.log('Credentials revoked')
+```
+
+The `tokenRefreshed` event fires when tokens are automatically refreshed, and `authenticated` fires after successful authentication.
+
+## Summary
+
+The `googleAuth` feature provides the authentication layer for all Google API features. It supports OAuth2 browser flow and service accounts, with automatic token refresh and diskCache storage. Other Google features (drive, sheets, calendar, docs) use it automatically. Key methods: `authorize()`, `authenticateServiceAccount()`, `getAuthClient()`, `revoke()`.

package/docs/examples/google-calendar.md

@@ -0,0 +1,94 @@
+---
+title: "Google Calendar"
+tags: [googleCalendar, google, calendar, events, scheduling]
+lastTested: null
+lastTestPassed: null
+---
+
+# googleCalendar
+
+Google Calendar feature for listing calendars and reading events. Creates a Calendar v3 API client and depends on `googleAuth` for authentication.
+
+## Overview
+
+Use the `googleCalendar` feature when you need to read calendar data: list calendars, fetch today's events, look ahead at upcoming days, or search events by text. Provides convenience methods for common time-based queries alongside the full `listEvents()` for custom ranges.
+
+Requires Google OAuth2 credentials or a service account with Calendar access.
+
+## Enabling the Feature
+
+```ts
+const calendar = container.feature('googleCalendar', {
+  defaultCalendarId: 'primary',
+  timeZone: 'America/Chicago'
+})
+console.log('Google Calendar feature created')
+console.log('Default calendar:', calendar.defaultCalendarId)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('googleCalendar')
+console.log(info)
+```
+
+## Listing Calendars
+
+Discover all calendars accessible to the authenticated user.
+
+```ts skip
+const calendars = await calendar.listCalendars()
+calendars.forEach(c => console.log(`  ${c.summary} (${c.id})`))
+```
+
+Returns calendar metadata including ID, summary, time zone, and access role. Use the ID to target specific calendars in other methods.
+
+## Today's Events and Upcoming
+
+Quick methods for the most common queries.
+
+```ts skip
+const today = await calendar.getToday()
+console.log(`Today: ${today.length} events`)
+today.forEach(e => console.log(`  ${e.start} - ${e.summary}`))
+
+const upcoming = await calendar.getUpcoming(7)
+console.log(`Next 7 days: ${upcoming.length} events`)
+upcoming.forEach(e => console.log(`  ${e.start} - ${e.summary}`))
+```
+
+`getToday()` returns events from midnight to midnight in the configured timezone. `getUpcoming(days)` looks ahead the specified number of days from now.
+
+## Searching Events
+
+Search across event summaries, descriptions, and locations.
+
+```ts skip
+const meetings = await calendar.searchEvents('standup')
+console.log(`Found ${meetings.length} standup events`)
+meetings.forEach(e => console.log(`  ${e.start} - ${e.summary}`))
+```
+
+The search is freetext and matches against multiple event fields. Combine with time range options for more precise results.
+
+## Custom Time Range Queries
+
+Use `listEvents()` for full control over the query parameters.
+
+```ts skip
+const events = await calendar.listEvents({
+  timeMin: '2026-03-01T00:00:00Z',
+  timeMax: '2026-03-31T23:59:59Z',
+  maxResults: 50,
+  orderBy: 'startTime',
+  singleEvents: true
+})
+console.log(`March events: ${events.items.length}`)
+```
+
+Supports pagination via `pageToken`, ordering by `startTime` or `updated`, and filtering by calendar ID.
+
+## Summary
+
+The `googleCalendar` feature provides read access to Google Calendar events. Use the convenience methods `getToday()` and `getUpcoming()` for quick lookups, `searchEvents()` for text search, or `listEvents()` for full query control. Authentication is handled by `googleAuth`. Key methods: `listCalendars()`, `getToday()`, `getUpcoming()`, `searchEvents()`, `listEvents()`.

package/docs/examples/google-docs.md

@@ -0,0 +1,82 @@
+---
+title: "Google Docs"
+tags: [googleDocs, google, docs, documents, markdown]
+lastTested: null
+lastTestPassed: null
+---
+
+# googleDocs
+
+Google Docs feature for reading documents and converting them to Markdown. Depends on `googleAuth` for authentication and optionally `googleDrive` for listing documents.
+
+## Overview
+
+Use the `googleDocs` feature when you need to read Google Docs content. Its standout capability is converting Google Docs to well-formatted Markdown, handling headings, bold/italic/strikethrough, links, code, lists, tables, and images. Also supports plain text extraction and raw document structure access.
+
+Requires Google OAuth2 credentials or a service account with Docs access.
+
+## Enabling the Feature
+
+```ts
+const docs = container.feature('googleDocs')
+console.log('Google Docs feature created')
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('googleDocs')
+console.log(info)
+```
+
+## Reading as Markdown
+
+Convert a Google Doc into clean Markdown with full formatting support.
+
+```ts skip
+const markdown = await docs.getAsMarkdown('1abc_document_id')
+console.log(markdown)
+```
+
+The converter handles headings (H1-H6), bold, italic, strikethrough, links, code fonts, ordered/unordered lists with nesting, tables, images, and section breaks. This is the primary method for extracting document content.
+
+## Plain Text and Raw Structure
+
+```ts skip
+const text = await docs.getAsText('1abc_document_id')
+console.log('Plain text length:', text.length)
+
+const rawDoc = await docs.getDocument('1abc_document_id')
+console.log('Document title:', rawDoc.title)
+console.log('Sections:', rawDoc.body.content.length)
+```
+
+Use `getAsText()` when you only need the words without any formatting. Use `getDocument()` when you need the full Docs API structure for custom processing.
+
+## Saving to Files
+
+```ts skip
+const path = await docs.saveAsMarkdown('1abc_document_id', './output/doc.md')
+console.log('Saved to:', path)
+```
+
+Downloads and converts a doc to Markdown in one step. The path is resolved relative to the container's working directory.
+
+## Listing and Searching Docs
+
+Uses Google Drive under the hood to find Google Docs by name or content.
+
+```ts skip
+const allDocs = await docs.listDocs()
+console.log(`Found ${allDocs.length} Google Docs`)
+allDocs.slice(0, 5).forEach(d => console.log(`  ${d.name} (${d.id})`))
+
+const results = await docs.searchDocs('meeting notes')
+console.log(`Search returned ${results.length} docs`)
+```
+
+Both methods filter Drive results to the Google Docs MIME type automatically.
+
+## Summary
+
+The `googleDocs` feature reads Google Docs and converts them to Markdown, plain text, or raw API structures. The Markdown converter handles all common formatting elements. Uses `googleDrive` for listing and searching documents. Key methods: `getAsMarkdown()`, `getAsText()`, `getDocument()`, `saveAsMarkdown()`, `listDocs()`, `searchDocs()`.

package/docs/examples/google-drive.md

@@ -0,0 +1,96 @@
+---
+title: "Google Drive"
+tags: [googleDrive, google, drive, files, storage]
+lastTested: null
+lastTestPassed: null
+---
+
+# googleDrive
+
+Google Drive feature for listing, searching, browsing, and downloading files. Creates a Drive v3 API client and depends on `googleAuth` for authentication.
+
+## Overview
+
+Use the `googleDrive` feature when you need to interact with Google Drive: list files, search by name or content, browse folder hierarchies, download files, or export Google Workspace documents. Authentication is handled automatically via the `googleAuth` feature.
+
+Requires Google OAuth2 credentials or a service account with Drive access.
+
+## Enabling the Feature
+
+```ts
+const drive = container.feature('googleDrive', {
+  pageSize: 50
+})
+console.log('Google Drive feature created')
+console.log('Default page size:', 50)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('googleDrive')
+console.log(info)
+```
+
+## Listing and Searching Files
+
+List recent files or search by name, content, or MIME type.
+
+```ts skip
+const { files } = await drive.listFiles()
+console.log(`Found ${files.length} files:`)
+files.slice(0, 5).forEach(f => console.log(`  ${f.name} (${f.mimeType})`))
+
+const { files: pdfs } = await drive.search('quarterly report', {
+  mimeType: 'application/pdf'
+})
+console.log(`Found ${pdfs.length} matching PDFs`)
+```
+
+The `listFiles()` method accepts an optional Drive query string for filtering. The `search()` method provides a simpler interface for text-based searches.
+
+## Browsing Folders
+
+Browse a folder to see its files and subfolders separately.
+
+```ts skip
+const root = await drive.browse()
+console.log('Root folders:', root.folders.length)
+console.log('Root files:', root.files.length)
+
+const sub = await drive.browse('folder-id-here')
+sub.folders.forEach(f => console.log(`  [dir] ${f.name}`))
+sub.files.forEach(f => console.log(`  [file] ${f.name}`))
+```
+
+The `browse()` method defaults to the root folder and separates the results into `folders` and `files` for easy navigation.
+
+## Downloading and Exporting
+
+Download files to disk or export Google Workspace documents to other formats.
+
+```ts skip
+await drive.downloadTo('file-id', './downloads/report.pdf')
+console.log('File downloaded')
+
+const buffer = await drive.download('file-id')
+console.log('Downloaded', buffer.length, 'bytes')
+
+const csv = await drive.exportFile('sheet-id', 'text/csv')
+console.log('Exported sheet as CSV:', csv.length, 'bytes')
+```
+
+Use `download()` for binary files and `exportFile()` for converting Google Docs, Sheets, or Slides to formats like PDF, CSV, or plain text.
+
+## Shared Drives
+
+```ts skip
+const drives = await drive.listDrives()
+drives.forEach(d => console.log(`  ${d.name} (${d.id})`))
+```
+
+List all shared drives the authenticated user has access to.
+
+## Summary
+
+The `googleDrive` feature provides complete Drive v3 API access for file management. Browse folders, search by content or type, download files, and export Workspace documents. Authentication is handled by `googleAuth`. Key methods: `listFiles()`, `search()`, `browse()`, `download()`, `downloadTo()`, `exportFile()`.

package/docs/examples/google-sheets.md

@@ -0,0 +1,95 @@
+---
+title: "Google Sheets"
+tags: [googleSheets, google, sheets, spreadsheet, data]
+lastTested: null
+lastTestPassed: null
+---
+
+# googleSheets
+
+Google Sheets feature for reading spreadsheet data as JSON, CSV, or raw arrays. Creates a Sheets v4 API client and depends on `googleAuth` for authentication.
+
+## Overview
+
+Use the `googleSheets` feature when you need to read data from Google Sheets. It provides convenient methods for reading ranges, converting rows to JSON objects (using the first row as headers), and exporting as CSV. You can set a default spreadsheet ID to avoid passing it on every call.
+
+Requires Google OAuth2 credentials or a service account with Sheets access.
+
+## Enabling the Feature
+
+```ts
+const sheets = container.feature('googleSheets', {
+  defaultSpreadsheetId: '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms'
+})
+console.log('Google Sheets feature created')
+console.log('Default spreadsheet configured:', !!sheets.options.defaultSpreadsheetId)
+```
+
+## API Documentation
+
+```ts
+const info = await container.features.describe('googleSheets')
+console.log(info)
+```
+
+## Reading Data as JSON
+
+The `getAsJson()` method treats the first row as headers and returns an array of objects.
+
+```ts skip
+const data = await sheets.getAsJson('Sheet1')
+console.log(`Read ${data.length} rows`)
+data.slice(0, 3).forEach(row => console.log(row))
+// => [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }, ...]
+```
+
+With a valid spreadsheet, this reads the first sheet tab and converts each row into a keyed object using the header row. Numeric values come through as strings by default.
+
+## Reading Specific Ranges
+
+Use A1 notation to read a precise cell range.
+
+```ts skip
+const values = await sheets.getRange('Sheet1!A1:D10')
+console.log(`Got ${values.length} rows, ${values[0]?.length} columns`)
+values.forEach(row => console.log(row.join(' | ')))
+```
+
+Returns a 2D array of strings. Useful when you need raw cell data without header interpretation.
+
+## Exporting as CSV
+
+```ts skip
+const csv = await sheets.getAsCsv('Revenue')
+console.log(csv)
+```
+
+Returns the entire sheet as a CSV-formatted string, ready for piping to files or other tools.
+
+## Saving to Local Files
+
+```ts skip
+await sheets.saveAsJson('./data/export.json', 'Sheet1')
+console.log('Saved JSON export')
+
+await sheets.saveAsCsv('./data/export.csv', 'Revenue')
+console.log('Saved CSV export')
+```
+
+Both methods write the file and return the resolved path. Paths are relative to the container's working directory.
+
+## Spreadsheet Metadata
+
+```ts skip
+const meta = await sheets.getSpreadsheet()
+console.log('Title:', meta.title)
+
+const tabs = await sheets.listSheets()
+tabs.forEach(t => console.log(`  Tab: ${t.title} (${t.rowCount} rows)`))
+```
+
+Inspect the spreadsheet structure before reading data.
+
+## Summary
+
+The `googleSheets` feature reads Google Sheets data in three formats: JSON objects, raw 2D arrays, and CSV strings. Set a default spreadsheet ID for convenience. Authentication is handled by `googleAuth`. Key methods: `getAsJson()`, `getRange()`, `getAsCsv()`, `saveAsJson()`, `saveAsCsv()`, `listSheets()`.