luca 1.1.2 → 3.0.0

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

@@ -0,0 +1,371 @@
+# Git (features.git)
+
+The Git feature provides utilities for interacting with Git repositories. This feature allows you to check repository status, list files, get branch information, and access Git metadata for projects within a Git repository.
+
+## Usage
+
+```ts
+container.feature('git')
+```
+
+## Methods
+
+### lsFiles
+
+Lists files in the Git repository using git ls-files command. This method provides a flexible interface to the git ls-files command, allowing you to filter files by various criteria such as cached, deleted, modified, untracked, and ignored files.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `LsFilesOptions` |  | Options to control which files are listed |
+
+`LsFilesOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cached` | `boolean` | Show cached/staged files |
+| `deleted` | `boolean` | Show deleted files |
+| `modified` | `boolean` | Show modified files |
+| `others` | `boolean` | Show untracked files |
+| `ignored` | `boolean` | Show ignored files |
+| `status` | `boolean` | Show file status information |
+| `includeIgnored` | `boolean` | Include ignored files when showing others |
+| `exclude` | `string | string[]` | Patterns to exclude from results |
+| `baseDir` | `string` | Base directory to list files from |
+
+**Returns:** `Promise<string[]>`
+
+```ts
+// Get all tracked files
+const allFiles = await git.lsFiles()
+
+// Get only modified files
+const modified = await git.lsFiles({ modified: true })
+
+// Get untracked files excluding certain patterns
+const untracked = await git.lsFiles({ 
+ others: true, 
+ exclude: ['*.log', 'node_modules'] 
+})
+```
+
+
+
+### getLatestChanges
+
+Gets the latest commits from the repository. Returns an array of commit objects containing the title (first line of commit message), full message body, and author name for each commit.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `numberOfChanges` | `number` |  | The number of recent commits to return |
+
+**Returns:** `Promise<Array<{ title: string, message: string, author: string }>>`
+
+```ts
+const changes = await git.getLatestChanges(5)
+for (const commit of changes) {
+ console.log(`${commit.author}: ${commit.title}`)
+}
+```
+
+
+
+### fileLog
+
+Gets a lightweight commit log for one or more files. Returns the SHA and message for each commit that touched the given files, without the per-commit overhead of resolving which specific files matched. For richer per-file matching, see {@link getChangeHistoryForFiles}.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `files` | `string[]` | ✓ | File paths (absolute or relative to container.cwd) |
+
+**Returns:** `Array<{ sha: string, message: string }>`
+
+```ts
+const log = git.fileLog('package.json')
+const log = git.fileLog('src/index.ts', 'src/helper.ts')
+for (const entry of log) {
+ console.log(`${entry.sha.slice(0, 8)} ${entry.message}`)
+}
+```
+
+
+
+### diff
+
+Gets the diff for a file between two refs. By default compares from the current HEAD to the given ref. You can supply both `compareTo` and `compareFrom` to diff between any two commits, branches, or tags.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `file` | `string` | ✓ | File path (absolute or relative to container.cwd) |
+| `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:** `string`
+
+```ts
+// Diff package.json between HEAD and a specific commit
+const d = git.diff('package.json', 'abc1234')
+
+// Diff between two branches
+const d = git.diff('src/index.ts', 'feature-branch', 'main')
+```
+
+
+
+### displayDiff
+
+Pretty prints a unified diff string to the terminal using colors. Parses the diff output and applies color coding: - File headers (`diff --git`, `---`, `+++`) are rendered bold - Hunk headers (`@@ ... @@`) are rendered in cyan - Added lines (`+`) are rendered in green - Removed lines (`-`) are rendered in red - Context lines are rendered dim Can be called with a raw diff string, or with the same arguments as {@link diff} to fetch and display in one step.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `diffOrFile` | `string` | ✓ | A raw diff string, or a file path to pass to {@link diff} |
+| `compareTo` | `string` |  | When diffOrFile is a file path, the target ref to compare to |
+| `compareFrom` | `string` |  | When diffOrFile is a file path, the base ref to compare from |
+
+**Returns:** `string`
+
+```ts
+// Display a pre-fetched diff
+const raw = git.diff('src/index.ts', 'main')
+git.displayDiff(raw)
+
+// Fetch and display in one call
+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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `paths` | `string[]` | ✓ | File paths or glob patterns to get history for |
+
+**Returns:** `Array<{ sha: string, message: string, longMessage: string, filesMatched: string[] }>`
+
+```ts
+const history = git.getChangeHistoryForFiles('src/container.ts', 'src/helper.ts')
+const history = git.getChangeHistoryForFiles('src/node/features/*.ts')
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `gitPath` | `string` | Resolve the git binary path via `which`, caching the result. |
+| `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)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `repoRoot` | `string` | Absolute path to the Git repository root directory |
+
+## Examples
+
+**features.git**
+
+```ts
+const git = container.feature('git')
+
+if (git.isRepo) {
+ console.log(`Current branch: ${git.branch}`)
+ console.log(`Repository root: ${git.repoRoot}`)
+ 
+ const allFiles = await git.lsFiles()
+ const modifiedFiles = await git.lsFiles({ modified: true })
+}
+```
+
+
+
+**lsFiles**
+
+```ts
+// Get all tracked files
+const allFiles = await git.lsFiles()
+
+// Get only modified files
+const modified = await git.lsFiles({ modified: true })
+
+// Get untracked files excluding certain patterns
+const untracked = await git.lsFiles({ 
+ others: true, 
+ exclude: ['*.log', 'node_modules'] 
+})
+```
+
+
+
+**getLatestChanges**
+
+```ts
+const changes = await git.getLatestChanges(5)
+for (const commit of changes) {
+ console.log(`${commit.author}: ${commit.title}`)
+}
+```
+
+
+
+**fileLog**
+
+```ts
+const log = git.fileLog('package.json')
+const log = git.fileLog('src/index.ts', 'src/helper.ts')
+for (const entry of log) {
+ console.log(`${entry.sha.slice(0, 8)} ${entry.message}`)
+}
+```
+
+
+
+**diff**
+
+```ts
+// Diff package.json between HEAD and a specific commit
+const d = git.diff('package.json', 'abc1234')
+
+// Diff between two branches
+const d = git.diff('src/index.ts', 'feature-branch', 'main')
+```
+
+
+
+**displayDiff**
+
+```ts
+// Display a pre-fetched diff
+const raw = git.diff('src/index.ts', 'main')
+git.displayDiff(raw)
+
+// Fetch and display in one call
+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
+const history = git.getChangeHistoryForFiles('src/container.ts', 'src/helper.ts')
+const history = git.getChangeHistoryForFiles('src/node/features/*.ts')
+```
+
+
+
+**branch**
+
+```ts
+const currentBranch = git.branch
+if (currentBranch) {
+ console.log(`Currently on branch: ${currentBranch}`)
+}
+```
+
+
+
+**sha**
+
+```ts
+const commitSha = git.sha
+if (commitSha) {
+ console.log(`Current commit: ${commitSha}`)
+}
+```
+
+
+
+**isRepo**
+
+```ts
+if (git.isRepo) {
+ console.log('This is a Git repository!')
+} else {
+ console.log('Not in a Git repository')
+}
+```
+
+
+
+**isRepoRoot**
+
+```ts
+if (git.isRepoRoot) {
+ console.log('At the repository root')
+} else {
+ console.log('In a subdirectory of the repository')
+}
+```
+
+
+
+**repoRoot**
+
+```ts
+const repoRoot = git.repoRoot
+if (repoRoot) {
+ console.log(`Repository root: ${repoRoot}`)
+}
+```
+

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

@@ -0,0 +1,193 @@
+# GoogleAuth (features.googleAuth)
+
+Google authentication feature supporting OAuth2 browser flow and service account auth. Handles the complete OAuth2 lifecycle: authorization URL generation, local callback server, token exchange, refresh token storage (via diskCache), and automatic token refresh. Also supports non-interactive service account authentication via JSON key files. Other Google features (drive, sheets, calendar, docs) depend on this feature and access it lazily via `container.feature('googleAuth')`.
+
+## Usage
+
+```ts
+container.feature('googleAuth', {
+  // Authentication mode. Auto-detected if serviceAccountKeyPath is set
+  mode,
+  // OAuth2 client ID (falls back to GOOGLE_CLIENT_ID env var)
+  clientId,
+  // OAuth2 client secret (falls back to GOOGLE_CLIENT_SECRET env var)
+  clientSecret,
+  // Path to service account JSON key file (falls back to GOOGLE_SERVICE_ACCOUNT_KEY env var)
+  serviceAccountKeyPath,
+  // Service account key as a parsed JSON object (alternative to file path)
+  serviceAccountKey,
+  // OAuth2 scopes to request
+  scopes,
+  // Port for OAuth2 callback server (falls back to GOOGLE_OAUTH_REDIRECT_PORT env var, then 3000)
+  redirectPort,
+  // DiskCache key for storing OAuth2 refresh token
+  tokenCacheKey,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `mode` | `string` | Authentication mode. Auto-detected if serviceAccountKeyPath is set |
+| `clientId` | `string` | OAuth2 client ID (falls back to GOOGLE_CLIENT_ID env var) |
+| `clientSecret` | `string` | OAuth2 client secret (falls back to GOOGLE_CLIENT_SECRET env var) |
+| `serviceAccountKeyPath` | `string` | Path to service account JSON key file (falls back to GOOGLE_SERVICE_ACCOUNT_KEY env var) |
+| `serviceAccountKey` | `object` | Service account key as a parsed JSON object (alternative to file path) |
+| `scopes` | `array` | OAuth2 scopes to request |
+| `redirectPort` | `number` | Port for OAuth2 callback server (falls back to GOOGLE_OAUTH_REDIRECT_PORT env var, then 3000) |
+| `tokenCacheKey` | `string` | DiskCache key for storing OAuth2 refresh token |
+
+## Methods
+
+### getOAuth2Client
+
+Get the OAuth2Client instance, creating it lazily. After authentication, this client has valid credentials set.
+
+**Returns:** `OAuth2Client`
+
+
+
+### getAuthClient
+
+Get the authenticated auth client for passing to googleapis service constructors. Handles token refresh automatically for OAuth2. For service accounts, returns the JWT auth client.
+
+**Returns:** `Promise<OAuth2Client | ReturnType<typeof google.auth.fromJSON>>`
+
+
+
+### authorize
+
+Start the OAuth2 authorization flow. 1. Spins up a temporary Express callback server on a free port 2. Generates the Google authorization URL 3. Opens the browser to the consent page 4. Waits for the callback with the authorization code 5. Exchanges the code for access + refresh tokens 6. Stores the refresh token in diskCache 7. Shuts down the callback server
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `scopes` | `string[]` |  | OAuth2 scopes to request (defaults to options.scopes or defaultScopes) |
+
+**Returns:** `Promise<this>`
+
+
+
+### authenticateServiceAccount
+
+Authenticate using a service account JSON key file. Reads the key from options.serviceAccountKeyPath, options.serviceAccountKey, or the GOOGLE_SERVICE_ACCOUNT_KEY env var.
+
+**Returns:** `Promise<this>`
+
+
+
+### tryRestoreTokens
+
+Attempt to restore authentication from a cached refresh token. Called automatically by getAuthClient() if not yet authenticated.
+
+**Returns:** `Promise<boolean>`
+
+
+
+### revoke
+
+Revoke the current credentials and clear cached tokens.
+
+**Returns:** `Promise<this>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `clientId` | `string` | OAuth2 client ID from options or GOOGLE_CLIENT_ID env var. |
+| `clientSecret` | `string` | OAuth2 client secret from options or GOOGLE_CLIENT_SECRET env var. |
+| `authMode` | `'oauth2' | 'service-account'` | Resolved authentication mode based on options. |
+| `isAuthenticated` | `boolean` | Whether valid credentials are currently available. |
+| `defaultScopes` | `string[]` | Default scopes covering Drive, Sheets, Calendar, and Docs read access. |
+| `redirectPort` | `number` | Resolved redirect port from options, GOOGLE_OAUTH_REDIRECT_PORT env var, or default 3000. |
+| `tokenCacheKey` | `string` | DiskCache key used for storing the refresh token. |
+
+## Events (Zod v4 schema)
+
+### tokenRefreshed
+
+Access token was refreshed
+
+
+
+### error
+
+Authentication error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### authorizationRequired
+
+User must visit this URL to authorize
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | Authorization URL to visit |
+
+
+
+### authenticated
+
+Authentication successful
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `mode` | `string` | Auth mode used |
+| `email` | `string` | User or service account email |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `authMode` | `string` | Current authentication mode |
+| `isAuthenticated` | `boolean` | Whether valid credentials are currently available |
+| `email` | `string` | Authenticated user or service account email |
+| `scopes` | `array` | OAuth2 scopes that have been authorized |
+| `tokenExpiry` | `string` | ISO timestamp when the current access token expires |
+| `lastError` | `string` | Last authentication error message |
+
+## Environment Variables
+
+- `GOOGLE_CLIENT_ID`
+- `GOOGLE_CLIENT_SECRET`
+- `GOOGLE_SERVICE_ACCOUNT_KEY`
+- `GOOGLE_OAUTH_REDIRECT_PORT`
+
+## Examples
+
+**features.googleAuth**
+
+```ts
+// OAuth2 flow — opens browser for consent
+const auth = container.feature('googleAuth', {
+ clientId: 'your-client-id.apps.googleusercontent.com',
+ clientSecret: 'your-secret',
+ scopes: ['https://www.googleapis.com/auth/drive.readonly'],
+})
+await auth.authorize()
+
+// Service account flow — no browser needed
+const auth = container.feature('googleAuth', {
+ serviceAccountKeyPath: '/path/to/key.json',
+ scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'],
+})
+await auth.authenticateServiceAccount()
+```
+