sqlew 5.0.8 → 5.2.0

package/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [5.2.0] - 2026-06-11
+
+### Added
+
+**Grok Build support (sqlew-plugin v5.2.0)**
+
+Unified Plan-to-ADR support for Grok Build alongside Claude Code via a single sqlew-plugin install. No separate sqlew-grok adapter required.
+
+- **`normalizeHookInput()`** — Translates Grok hook payloads (`hookEventName`, `toolName`, `sessionId`, `workspaceRoot`) to canonical Claude-shaped `HookInput`. Claude payloads pass through unchanged.
+- **`computeGrokPlanPath()`** — Resolves per-session plan file at `~/.grok/sessions/<encodeURIComponent(cwd)>/<sessionId>/plan.md`.
+- **`injectGrokPlanTemplate()`** — Appends Decision/Constraint template to `plan.md` on `enter_plan_mode` (file side-effect). Grok ignores passive hook stdout; skills auto-invocation is unreliable.
+- **`GROK_WORKSPACE_ROOT`** — Added to `determineProjectRoot()` for MCP server project root resolution.
+- **Grok `sendBlock()` compat** — PreToolUse deny hooks emit `{"decision":"deny","reason":"..."}` on stdout for Grok (in addition to exit 2 + stderr for Claude Code).
+- **Unit tests** — `grok-hook-normalization.test.ts`, `grok-plan-template-injection.test.ts`.
+
+### Changed
+
+- **`on-prompt`** — Early return for Grok client (`UserPromptSubmit` stdout is ignored on Grok).
+- **`on-exit-plan` / `track-plan`** — Record `CurrentPlanInfo.plan_path` for Grok; always re-resolve from `session_id` on exit.
+- **`plan-processor`** — Prefer explicit `plan_path` over legacy Claude global plans resolver.
+- **`docs/HOOKS_GUIDE.md`** — Replaced sqlew-grok adapter instructions with `grok plugin install sqlew-io/sqlew-plugin --trust` workflow.
+
+### Plugin Changes (sqlew-plugin v5.2.0)
+
+- Hook matchers: `enter_plan_mode` / `exit_plan_mode` alongside Claude tool names
+- Skills: Grok-specific plan mode guidance (`sqlew-plan-guidance`, `sqlew-decision-format`)
+
+---
+
+## [5.1.0] - 2026-03-07
+
+### Changed
+
+**📁 `.sqlew.env` relocated to `~/.config/sqlew/.sqlew.env`**
+
+The cloud API key file (`~/.sqlew.env`) has been moved to `~/.config/sqlew/.sqlew.env` to align with the v5.1 unified global config path. Automatic migration copies the old file and deletes it (API key security: no stale copies). `saveCachedProjectId()` now calls `ensureGlobalConfigDir()` for directory safety.
+
+**🔒 db:export Project Scope Auto-Detection (Security)**
+
+`db:export` no longer exports all projects by default. With the global shared database (v5.1.0), the default "export everything" behavior risked leaking other projects' decision data.
+
+- **Auto-detect**: Project name resolved from `.sqlew/config.toml` `[project].name` when no `project=` option is given
+- **Explicit all**: `project=all` required to export all projects (escape hatch)
+- **Error on ambiguity**: If no project name is found (no CLI arg, no config.toml), the command exits with an actionable error message
+- **Breaking change**: Previously, omitting `project=` exported all projects silently
+
+### Resolution Priority
+
+```
+1. CLI argument: project=<name>     (highest)
+2. config.toml: [project].name
+3. Error exit                       (lowest)
+```
+
+---
+
 ## [5.0.6] - 2026-02-14
 
 ### Changed

package/README.md

@@ -58,6 +58,16 @@ The plugin automatically configures MCP server, Skills (Plan Mode guidance), and
 
 See [sqlew-codex](https://github.com/sqlew-io/sqlew-codex) for Codex CLI integration.
 
+#### Grok Build (Plugin)
+
+```bash
+npm install -g sqlew
+grok plugin install sqlew-io/sqlew-plugin --trust
+grok plugin update
+```
+
+The plugin configures MCP server, Skills (plan mode guidance), and Hooks (automatic decision capture on `exit_plan_mode`). See [Hooks Guide](docs/HOOKS_GUIDE.md) for setup details and caveats (do not duplicate hooks in `~/.grok/hooks/` or `config.toml`).
+
 #### Manual
 
 Add to `.mcp.json` in your project root:
@@ -72,7 +82,7 @@ Add to `.mcp.json` in your project root:
 }
 ```
 
-The database (`.sqlew/sqlew.db`) and config (`.sqlew/config.toml`) are auto-created on first run.
+The database (`~/.config/sqlew/sqlew-shared.db`) and config are auto-created on first run. See [Shared Database](docs/SHARED_DATABASE.md) for details.
 
 ### 3. Just use Plan Mode!
 
@@ -86,7 +96,7 @@ No special commands needed — just plan your work normally, and sqlew captures
 - **Fast Queries** — 2-50ms retrieval via SQL, even with thousands of decisions
 - **Duplicate Detection** — Three-tier similarity scoring (0-100) prevents redundant decisions
 - **Constraint Tracking** — Architectural rules and principles as first-class entities
-- **Auto-Capture** — Hooks automatically record decisions from Plan Mode (Claude Code plugin)
+- **Auto-Capture** — Hooks automatically record decisions from Plan Mode (Claude Code and Grok Build via sqlew-plugin)
 - **Multi-Database** — SQLite (default), PostgreSQL, MySQL/MariaDB, or Cloud
 - **Git Worktree Ready** — Each worktree shares the same context database
 
@@ -99,7 +109,7 @@ Connect to [sqlew.io](https://sqlew.io) for team-shared decisions:
 Visit [sqlew.io](https://sqlew.io) and save your API key:
 
 ```bash
-# ~/.sqlew.env (shared across all projects)
+# ~/.config/sqlew/.sqlew.env (shared across all projects)
 SQLEW_API_KEY=your-api-key
 ```
 
@@ -142,7 +152,7 @@ name = "your-project-name"
 |-------|-------------|
 | [ADR Concepts](docs/ADR_CONCEPTS.md) | Architecture Decision Records explained |
 | [Configuration](docs/CONFIGURATION.md) | Config file setup, database options |
-| [Hooks Guide](docs/HOOKS_GUIDE.md) | Claude Code Hooks integration |
+| [Hooks Guide](docs/HOOKS_GUIDE.md) | Claude Code, Codex, and Grok Build integration |
 | [Cross Database](docs/CROSS_DATABASE.md) | Multi-database support |
 | [CLI Usage](docs/CLI_USAGE.md) | Database migration, export/import |
 
@@ -163,16 +173,15 @@ Support development via [GitHub Sponsors](https://github.com/sponsors/sqlew-io).
 
 ## Version
 
-Current version: **5.0.8**
+Current version: **5.2.0**
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
-**What's New in v5.0.8:**
+**What's New in v5.2.0:**
 
-- **PR ADR enforcement** — PreToolUse Hook blocks `gh pr create` without ADR markers, file-grouped format
-- **Codex CLI support** — Works beyond Claude Code via [sqlew-codex](https://github.com/sqlew-io/sqlew-codex)
-- **Plugin-first architecture** — Simplified setup via sqlew-plugin
-- **Cloud backend** — Connect to [sqlew.io](https://sqlew.io) for team-shared decisions
+- **Grok Build support** — Plan-to-ADR via [sqlew-plugin](https://github.com/sqlew-io/sqlew-plugin) (`grok plugin install sqlew-io/sqlew-plugin --trust`)
+- **Grok plan.md injection** — Decision/Constraint template appended on `enter_plan_mode`
+- **Hook normalization** — Single CLI hook handlers work under both Claude Code and Grok Build
 
 ## License
 

package/dist/adapters/auth/auth-factory.d.ts

@@ -1,86 +1,7 @@
-/**
- * @fileoverview Authentication Provider Factory
- *
- * Factory module for creating appropriate authentication providers based on database configuration.
- * Supports direct connections and future IAM-based authentication.
- *
- * **Note:** SSH tunneling is not supported. Users must set up SSH tunnels manually.
- *
- * @module adapters/auth/auth-factory
- */
 import { BaseAuthProvider } from './base-auth-provider.js';
 import type { DatabaseConfig } from '../../config/types.js';
-/**
- * Create an authentication provider based on database configuration.
- *
- * Provider selection logic:
- * - SQLite: Returns null (no authentication needed for file-based database)
- * - MySQL/PostgreSQL: Returns DirectAuthProvider
- *
- * @param config - Database configuration
- * @returns Authentication provider instance or null for SQLite
- * @throws Error if database type is invalid
- *
- * @example
- * // Direct connection
- * const config: DatabaseConfig = {
- *   type: 'mysql',
- *   connection: {
- *     host: 'localhost',
- *     port: 3306,
- *     database: 'mydb'
- *   },
- *   auth: {
- *     type: 'direct',
- *     user: 'dbuser',
- *     password: 'dbpass'
- *   }
- * };
- * const provider = createAuthProvider(config);
- * // Returns DirectAuthProvider instance
- *
- * @example
- * // Connection via manual SSH tunnel
- * // Step 1: Set up tunnel manually:
- * //   ssh -L 3307:db.internal.company.com:3306 user@bastion.example.com
- * // Step 2: Configure to use localhost:
- * const config: DatabaseConfig = {
- *   type: 'mysql',
- *   connection: {
- *     host: 'localhost',  // Tunnel endpoint
- *     port: 3307,         // Forwarded port
- *     database: 'mydb'
- *   },
- *   auth: {
- *     type: 'direct',
- *     user: 'dbuser',
- *     password: 'dbpass'
- *   }
- * };
- * const provider = createAuthProvider(config);
- * // Returns DirectAuthProvider for localhost connection
- *
- * @example
- * // SQLite (no authentication)
- * const sqliteConfig: DatabaseConfig = {
- *   type: 'sqlite',
- *   path: './data.db'
- * };
- * const provider = createAuthProvider(sqliteConfig);
- * // Returns null
- */
+/** Create an authentication provider based on database configuration. */
 export declare function createAuthProvider(config: DatabaseConfig): BaseAuthProvider | null;
-/**
- * Check if database type requires authentication.
- *
- * @param config - Database configuration
- * @returns True if authentication is required (MySQL/PostgreSQL)
- *
- * @example
- * if (requiresAuthentication(config)) {
- *   const provider = createAuthProvider(config);
- *   await provider!.authenticate();
- * }
- */
+/** Check if database type requires authentication. */
 export declare function requiresAuthentication(config: DatabaseConfig): boolean;
 //# sourceMappingURL=auth-factory.d.ts.map

package/dist/adapters/auth/auth-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-factory.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/auth-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAmBlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEtE"}
+{"version":3,"file":"auth-factory.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/auth-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAkBlF;AAED,sDAAsD;AACtD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAEtE"}

package/dist/adapters/auth/auth-factory.js

@@ -1,73 +1,5 @@
-/**
- * @fileoverview Authentication Provider Factory
- *
- * Factory module for creating appropriate authentication providers based on database configuration.
- * Supports direct connections and future IAM-based authentication.
- *
- * **Note:** SSH tunneling is not supported. Users must set up SSH tunnels manually.
- *
- * @module adapters/auth/auth-factory
- */
 import { DirectAuthProvider } from './direct-auth-provider.js';
-/**
- * Create an authentication provider based on database configuration.
- *
- * Provider selection logic:
- * - SQLite: Returns null (no authentication needed for file-based database)
- * - MySQL/PostgreSQL: Returns DirectAuthProvider
- *
- * @param config - Database configuration
- * @returns Authentication provider instance or null for SQLite
- * @throws Error if database type is invalid
- *
- * @example
- * // Direct connection
- * const config: DatabaseConfig = {
- *   type: 'mysql',
- *   connection: {
- *     host: 'localhost',
- *     port: 3306,
- *     database: 'mydb'
- *   },
- *   auth: {
- *     type: 'direct',
- *     user: 'dbuser',
- *     password: 'dbpass'
- *   }
- * };
- * const provider = createAuthProvider(config);
- * // Returns DirectAuthProvider instance
- *
- * @example
- * // Connection via manual SSH tunnel
- * // Step 1: Set up tunnel manually:
- * //   ssh -L 3307:db.internal.company.com:3306 user@bastion.example.com
- * // Step 2: Configure to use localhost:
- * const config: DatabaseConfig = {
- *   type: 'mysql',
- *   connection: {
- *     host: 'localhost',  // Tunnel endpoint
- *     port: 3307,         // Forwarded port
- *     database: 'mydb'
- *   },
- *   auth: {
- *     type: 'direct',
- *     user: 'dbuser',
- *     password: 'dbpass'
- *   }
- * };
- * const provider = createAuthProvider(config);
- * // Returns DirectAuthProvider for localhost connection
- *
- * @example
- * // SQLite (no authentication)
- * const sqliteConfig: DatabaseConfig = {
- *   type: 'sqlite',
- *   path: './data.db'
- * };
- * const provider = createAuthProvider(sqliteConfig);
- * // Returns null
- */
+/** Create an authentication provider based on database configuration. */
 export function createAuthProvider(config) {
     // Validate database type
     if (!config.type) {
@@ -82,21 +14,9 @@ export function createAuthProvider(config) {
         return null;
     }
     // MySQL/PostgreSQL use direct authentication
-    // (Users must set up SSH tunnels manually if needed)
     return new DirectAuthProvider(config);
 }
-/**
- * Check if database type requires authentication.
- *
- * @param config - Database configuration
- * @returns True if authentication is required (MySQL/PostgreSQL)
- *
- * @example
- * if (requiresAuthentication(config)) {
- *   const provider = createAuthProvider(config);
- *   await provider!.authenticate();
- * }
- */
+/** Check if database type requires authentication. */
 export function requiresAuthentication(config) {
     return config.type !== 'sqlite';
 }

package/dist/adapters/auth/auth-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-factory.js","sourceRoot":"","sources":["../../../src/adapters/auth/auth-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACvD,yBAAyB;IACzB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,IAAI,qBAAqB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,kDAAkD;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,qDAAqD;IACrD,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAsB;IAC3D,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClC,CAAC"}
+{"version":3,"file":"auth-factory.js","sourceRoot":"","sources":["../../../src/adapters/auth/auth-factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACvD,yBAAyB;IACzB,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,IAAI,qBAAqB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,kDAAkD;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,sBAAsB,CAAC,MAAsB;IAC3D,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClC,CAAC"}

package/dist/adapters/auth/base-auth-provider.d.ts

@@ -1,327 +1,42 @@
-/**
- * @fileoverview Base authentication provider for sqlew's multi-RDBMS authentication system.
- *
- * This module provides the foundation for all authentication providers, enabling support for:
- * - SSH tunneling (v3.7.0)
- * - Direct connections (v3.7.0)
- * - AWS IAM authentication (v3.8.0+)
- * - GCP IAM authentication (v3.8.0+)
- *
- * @module adapters/auth/base-auth-provider
- * @since v3.7.0
- */
 import type { DatabaseConfig } from '../../config/types.js';
-/**
- * Connection parameters used to establish database connections.
- *
- * These parameters are returned by authentication providers after processing
- * credentials, setting up tunnels, or obtaining temporary tokens.
- *
- * @interface ConnectionParams
- * @example
- * // Direct connection
- * {
- *   host: 'postgres.example.com',
- *   port: 5432,
- *   database: 'mydb',
- *   user: 'admin',
- *   password: 'secret123'
- * }
- *
- * @example
- * // SSH tunnel connection
- * {
- *   host: '127.0.0.1',
- *   port: 54321,  // Local tunnel port
- *   database: 'mydb',
- *   user: 'admin',
- *   password: 'secret123'
- * }
- *
- * @example
- * // AWS IAM authentication
- * {
- *   host: 'db.region.rds.amazonaws.com',
- *   port: 5432,
- *   database: 'mydb',
- *   user: 'iam_user',
- *   password: 'temporary_token_generated_by_aws',
- *   ssl: {
- *     ca: '/path/to/rds-ca-bundle.pem',
- *     rejectUnauthorized: true
- *   }
- * }
- */
+/** Connection parameters returned by authentication providers. */
 export interface ConnectionParams {
-    /**
-     * Database host address.
-     * For direct connections: remote host address.
-     * For SSH tunnels: '127.0.0.1' (localhost).
-     * For cloud IAM: cloud provider's database endpoint.
-     */
+    /** Database host address. */
     host: string;
-    /**
-     * Database port number.
-     * For direct connections: remote database port.
-     * For SSH tunnels: local tunnel port.
-     * For cloud IAM: cloud provider's database port.
-     */
+    /** Database port number. */
     port: number;
-    /**
-     * Target database name.
-     */
+    /** Target database name. */
     database: string;
-    /**
-     * Database user/username.
-     * For IAM authentication: IAM role or user identifier.
-     */
+    /** Database user/username. */
     user: string;
-    /**
-     * Database password or authentication token.
-     * Optional for IAM-based authentication where tokens are generated dynamically.
-     * For AWS/GCP IAM: temporary authentication token.
-     */
+    /** Database password or authentication token. */
     password?: string;
-    /**
-     * SSL/TLS configuration for encrypted connections.
-     * Required for most cloud providers (AWS RDS, GCP Cloud SQL).
-     */
+    /** SSL/TLS configuration for encrypted connections. */
     ssl?: {
-        /**
-         * Certificate Authority (CA) certificate.
-         * Path to PEM file or certificate content.
-         */
+        /** Certificate Authority (CA) certificate. */
         ca?: string;
-        /**
-         * Client certificate for mutual TLS.
-         * Path to PEM file or certificate content.
-         */
+        /** Client certificate for mutual TLS. */
         cert?: string;
-        /**
-         * Client private key for mutual TLS.
-         * Path to PEM file or key content.
-         */
+        /** Client private key for mutual TLS. */
         key?: string;
-        /**
-         * Whether to reject unauthorized certificates.
-         * Set to false for self-signed certificates (not recommended for production).
-         */
+        /** Whether to reject unauthorized certificates. */
         rejectUnauthorized?: boolean;
     };
-    /**
-     * Database-specific connection parameters.
-     *
-     * Examples:
-     * - PostgreSQL: { statement_timeout: 30000, application_name: 'mcp-sqlew' }
-     * - MySQL: { connectTimeout: 10000, multipleStatements: false }
-     * - SQL Server: { requestTimeout: 30000, encrypt: true }
-     */
+    /** Database-specific additional connection parameters. */
     additionalParams?: Record<string, any>;
 }
-/**
- * Abstract base class for all authentication providers.
- *
- * This class establishes the contract that all authentication providers must implement,
- * ensuring consistent behavior across different authentication methods.
- *
- * **Supported Authentication Methods:**
- * - `DirectAuthProvider`: Standard username/password authentication
- * - `SshAuthProvider`: SSH tunneling with key-based or password authentication
- * - `AwsIamAuthProvider`: AWS RDS IAM database authentication
- * - `GcpIamAuthProvider`: GCP Cloud SQL IAM authentication
- *
- * **Authentication Flow:**
- * 1. Provider instantiation with DatabaseConfig
- * 2. `validate()` - Verify configuration is valid
- * 3. `authenticate()` - Process credentials and return ConnectionParams
- * 4. Database connection using returned params
- * 5. `cleanup()` - Release resources when connection closes
- *
- * @abstract
- * @class BaseAuthProvider
- *
- * @example
- * // Implementing a custom authentication provider
- * class CustomAuthProvider extends BaseAuthProvider {
- *   async authenticate(): Promise<ConnectionParams> {
- *     // Implement custom authentication logic
- *     return {
- *       host: this.config.connection.host,
- *       port: this.config.connection.port,
- *       database: this.config.connection.database,
- *       user: this.config.auth.user,
- *       password: await this.getCustomPassword()
- *     };
- *   }
- *
- *   getAuthMethod(): string {
- *     return 'Custom Authentication';
- *   }
- *
- *   async cleanup(): Promise<void> {
- *     // Clean up any resources
- *   }
- *
- *   validate(): void {
- *     if (!this.config.auth.user) {
- *       throw new Error('User is required for custom authentication');
- *     }
- *   }
- * }
- *
- * @example
- * // Using an authentication provider
- * const provider = new DirectAuthProvider(config);
- * provider.validate();
- * const connParams = await provider.authenticate();
- * const connection = await createConnection(connParams);
- * // ... use connection ...
- * await connection.close();
- * await provider.cleanup();
- */
+/** Abstract base class for all authentication providers. */
 export declare abstract class BaseAuthProvider {
-    /**
-     * Database configuration containing connection and authentication settings.
-     * Accessible to child classes for implementing authentication logic.
-     *
-     * @protected
-     * @readonly
-     */
+    /** @protected */
     protected readonly config: DatabaseConfig;
-    /**
-     * Creates a new authentication provider instance.
-     *
-     * @param {DatabaseConfig} config - Database configuration object
-     *
-     * @example
-     * const provider = new SshAuthProvider({
-     *   type: 'postgres',
-     *   connection: {
-     *     host: 'db.internal',
-     *     port: 5432,
-     *     database: 'production'
-     *   },
-     *   auth: {
-     *     type: 'ssh',
-     *     ssh: {
-     *       host: 'bastion.example.com',
-     *       port: 22,
-     *       user: 'deploy',
-     *       privateKey: '/path/to/key.pem'
-     *     }
-     *   }
-     * });
-     */
     constructor(config: DatabaseConfig);
-    /**
-     * Authenticates and returns connection parameters for database connection.
-     *
-     * This method handles the authentication process specific to each provider:
-     * - **Direct**: Returns credentials as-is
-     * - **SSH**: Establishes tunnel, returns localhost connection params
-     * - **AWS IAM**: Generates temporary token, returns params with SSL config
-     * - **GCP IAM**: Obtains OAuth token, returns params with cloud SQL proxy
-     *
-     * @abstract
-     * @returns {Promise<ConnectionParams>} Connection parameters for database client
-     *
-     * @throws {Error} When authentication fails or credentials are invalid
-     *
-     * @example
-     * // Direct authentication
-     * const params = await directProvider.authenticate();
-     * // Returns: { host: 'db.example.com', port: 5432, user: 'admin', password: 'secret' }
-     *
-     * @example
-     * // SSH tunnel authentication
-     * const params = await sshProvider.authenticate();
-     * // Returns: { host: '127.0.0.1', port: 54321, user: 'admin', password: 'secret' }
-     * // Note: Tunnel is active until cleanup() is called
-     *
-     * @example
-     * // AWS IAM authentication
-     * const params = await awsProvider.authenticate();
-     * // Returns: { host: 'db.region.rds.amazonaws.com', user: 'iam_user',
-     * //           password: 'temp_token_xyz', ssl: { ca: '...' } }
-     */
+    /** Authenticates and returns connection parameters. @abstract */
     abstract authenticate(): Promise<ConnectionParams>;
-    /**
-     * Returns a human-readable name for this authentication method.
-     *
-     * Used for logging, error messages, and telemetry.
-     *
-     * @abstract
-     * @returns {string} Authentication method name
-     *
-     * @example
-     * directProvider.getAuthMethod(); // Returns: "Direct"
-     * sshProvider.getAuthMethod();    // Returns: "SSH Tunnel"
-     * awsProvider.getAuthMethod();    // Returns: "AWS IAM"
-     * gcpProvider.getAuthMethod();    // Returns: "GCP IAM"
-     */
+    /** Returns a human-readable name for this authentication method. @abstract */
     abstract getAuthMethod(): string;
-    /**
-     * Releases resources allocated during authentication.
-     *
-     * This method MUST be called when the database connection is closed to prevent
-     * resource leaks. Different providers handle cleanup differently:
-     *
-     * - **Direct**: No-op (no resources to clean)
-     * - **SSH**: Closes SSH tunnel and releases local port
-     * - **AWS IAM**: Invalidates cached tokens (if applicable)
-     * - **GCP IAM**: Closes Cloud SQL proxy connection
-     *
-     * @abstract
-     * @returns {Promise<void>}
-     *
-     * @throws {Error} If cleanup fails (should be caught and logged, not propagated)
-     *
-     * @example
-     * try {
-     *   await provider.cleanup();
-     * } catch (error) {
-     *   console.error('Cleanup failed:', error);
-     *   // Connection is closed, log error but don't throw
-     * }
-     */
+    /** Releases resources allocated during authentication. @abstract */
     abstract cleanup(): Promise<void>;
-    /**
-     * Validates the authentication configuration.
-     *
-     * This method checks that all required configuration parameters are present
-     * and valid BEFORE attempting authentication. It should be called immediately
-     * after provider instantiation to fail fast on configuration errors.
-     *
-     * **Validation Examples:**
-     * - **Direct**: Verify host, port, user, password are present
-     * - **SSH**: Verify SSH host, SSH user, privateKey/password, target credentials
-     * - **AWS IAM**: Verify region, IAM role/user, AWS credentials available
-     * - **GCP IAM**: Verify project ID, service account, GCP credentials available
-     *
-     * @abstract
-     * @returns {void}
-     *
-     * @throws {Error} If configuration is invalid or incomplete
-     *
-     * @example
-     * try {
-     *   provider.validate();
-     * } catch (error) {
-     *   console.error('Invalid configuration:', error.message);
-     *   // Fix configuration before proceeding
-     * }
-     *
-     * @example
-     * // Validation in SSH provider
-     * validate(): void {
-     *   if (!this.config.auth.ssh?.host) {
-     *     throw new Error('SSH host is required for SSH authentication');
-     *   }
-     *   if (!this.config.auth.ssh.privateKey && !this.config.auth.ssh.password) {
-     *     throw new Error('SSH privateKey or password is required');
-     *   }
-     * }
-     */
+    /** Validates the authentication configuration. @abstract */
     abstract validate(): void;
 }
 //# sourceMappingURL=base-auth-provider.d.ts.map