@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/client.d.ts

@@ -0,0 +1,293 @@
+/**
+ * CmosDatabaseClient - Core database client wrapper for CMOS SQLite operations
+ *
+ * Provides:
+ * - Connection management with auto-close
+ * - Standard query patterns (getOne, getMany, execute)
+ * - Error translation to structured CmosToolError
+ * - Integration with CmosDetector for database path discovery
+ *
+ * All methods return CmosToolResult<T> for consistent agent-friendly responses.
+ *
+ * @module tools/cmos/client
+ */
+import { type CmosDetectionResult } from '../../intelligence/cmos-detector';
+import { ProjectRegistry, resolveProjectRootEnhanced, resolveProjectRootPath, ProjectResolutionError, type ProjectResolutionResult, type RegisteredProject, type ProjectValidation } from '../../intelligence/project-registry';
+import type { CmosToolResult, DbHealthResult } from './types';
+export { ProjectRegistry, resolveProjectRootEnhanced, resolveProjectRootPath, ProjectResolutionError, type ProjectResolutionResult, type RegisteredProject, type ProjectValidation, };
+/**
+ * Environment variable for CMOS project root.
+ * When set, tools use this as default instead of process.cwd().
+ * Useful for Claude Desktop where cwd may not be the project directory.
+ */
+export declare const CMOS_PROJECT_ROOT_ENV = "CMOS_PROJECT_ROOT";
+/**
+ * Environment variable for project ID validation.
+ * Used together with database self-protection: if database has project_id
+ * in metadata, this env var MUST match for mutation operations.
+ */
+export declare const CMOS_PROJECT_ID_ENV = "CMOS_PROJECT_ID";
+/**
+ * Resolve the project root directory (synchronous, simple fallback).
+ *
+ * Priority: explicit param > CMOS_PROJECT_ROOT env var > process.cwd()
+ *
+ * @deprecated Use resolveProjectRootEnhanced() for full 5-step resolution
+ * with auto-discovery and registry fallback. This synchronous version
+ * is kept for backward compatibility but doesn't support the registry.
+ *
+ * @param explicitRoot - Explicitly provided project root
+ * @returns Resolved project root path
+ */
+export declare function resolveProjectRoot(explicitRoot?: string): string;
+/**
+ * Options for creating a CmosDatabaseClient
+ */
+export interface CmosDatabaseClientOptions {
+    /** Explicit database path (overrides detection) */
+    dbPath?: string;
+    /** Project root for CMOS detection (defaults to cwd) */
+    projectRoot?: string;
+    /** SQLite connection timeout in milliseconds */
+    timeout?: number;
+    /** Whether to open in read-only mode */
+    readonly?: boolean;
+    /** Enable verbose mode for debugging */
+    verbose?: boolean;
+}
+/**
+ * Query parameters for parameterized queries
+ */
+export type QueryParams = Record<string, unknown> | unknown[];
+/**
+ * Result of a database mutation (INSERT, UPDATE, DELETE)
+ */
+export interface MutationResult {
+    /** Number of rows affected */
+    changes: number;
+    /** Last inserted row ID (for INSERT) */
+    lastInsertRowid: number | bigint;
+}
+/**
+ * CmosDatabaseClient - Wrapper around better-sqlite3 for CMOS operations
+ *
+ * Usage:
+ * ```typescript
+ * // Create client (auto-detects database)
+ * const client = await CmosDatabaseClient.create();
+ *
+ * // Query operations
+ * const missions = await client.getMany<Mission>('SELECT * FROM missions WHERE status = ?', ['In Progress']);
+ * const mission = await client.getOne<Mission>('SELECT * FROM missions WHERE id = ?', ['s12-m03']);
+ *
+ * // Mutation operations
+ * const result = await client.execute(
+ *   'UPDATE missions SET status = ? WHERE id = ?',
+ *   ['Completed', 's12-m03']
+ * );
+ *
+ * // Always close when done
+ * client.close();
+ * ```
+ */
+export declare class CmosDatabaseClient {
+    private db;
+    private readonly dbPath;
+    private readonly options;
+    private statementCache;
+    /**
+     * Private constructor - use CmosDatabaseClient.create() instead
+     */
+    private constructor();
+    /**
+     * Create a new CmosDatabaseClient
+     *
+     * Uses 5-step resolution priority:
+     * 1. Explicit dbPath option
+     * 2. Explicit projectRoot option
+     * 3. CMOS_PROJECT_ROOT environment variable
+     * 4. Auto-discover from cwd
+     * 5. Registry fallback (default project)
+     *
+     * @param options - Client options
+     * @returns CmosToolResult with the client or an error
+     */
+    static create(options?: CmosDatabaseClientOptions): Promise<CmosToolResult<CmosDatabaseClient>>;
+    /**
+     * Create a CmosDatabaseClient from a detection result
+     *
+     * Useful when you've already run detection and want to avoid re-detecting.
+     *
+     * @param detection - CmosDetectionResult from CmosDetector
+     * @param options - Additional client options
+     * @returns CmosToolResult with the client or an error
+     */
+    static fromDetection(detection: CmosDetectionResult, options?: Omit<CmosDatabaseClientOptions, 'dbPath' | 'projectRoot'>): CmosToolResult<CmosDatabaseClient>;
+    /**
+     * Get the database path
+     */
+    get path(): string;
+    /**
+     * Check if the database connection is open
+     */
+    get isOpen(): boolean;
+    /**
+     * Ensure database connection is established
+     *
+     * @returns CmosToolResult indicating success or connection error
+     */
+    private ensureConnection;
+    /**
+     * Get a single row from the database
+     *
+     * @param sql - SQL query (should return at most one row)
+     * @param params - Query parameters (array for positional, object for named)
+     * @returns CmosToolResult with the row or undefined if not found
+     */
+    getOne<T = Record<string, unknown>>(sql: string, params?: QueryParams): CmosToolResult<T | undefined>;
+    /**
+     * Get multiple rows from the database
+     *
+     * @param sql - SQL query
+     * @param params - Query parameters (array for positional, object for named)
+     * @returns CmosToolResult with array of rows (empty array if none found)
+     */
+    getMany<T = Record<string, unknown>>(sql: string, params?: QueryParams): CmosToolResult<T[]>;
+    /**
+     * Execute a mutation query (INSERT, UPDATE, DELETE)
+     *
+     * @param sql - SQL mutation query
+     * @param params - Query parameters (array for positional, object for named)
+     * @returns CmosToolResult with mutation result (changes, lastInsertRowid)
+     */
+    execute(sql: string, params?: QueryParams): CmosToolResult<MutationResult>;
+    /**
+     * Execute multiple statements in a transaction
+     *
+     * All statements succeed or all fail (atomic).
+     *
+     * @param fn - Function that performs database operations
+     * @returns CmosToolResult with the function's return value
+     */
+    transaction<T>(fn: () => T): CmosToolResult<T>;
+    /**
+     * Execute raw SQL (for complex operations like PRAGMA)
+     *
+     * Use with caution - prefer getOne/getMany/execute for standard queries.
+     *
+     * @param sql - Raw SQL to execute
+     * @returns CmosToolResult indicating success or error
+     */
+    raw(sql: string): CmosToolResult<void>;
+    /**
+     * Check database health and return statistics
+     *
+     * @returns CmosToolResult with database health information
+     */
+    health(): CmosToolResult<DbHealthResult>;
+    /**
+     * Close the database connection
+     *
+     * Clears the statement cache and releases all resources.
+     * Safe to call multiple times.
+     */
+    close(): void;
+    /**
+     * Get a prepared statement (cached for performance)
+     */
+    private prepareStatement;
+    /**
+     * Safely count rows in a table
+     */
+    private safeCount;
+    /**
+     * Handle query errors and translate to CmosToolError
+     */
+    private handleQueryError;
+    /**
+     * Validate project ID matches expected value from environment.
+     *
+     * Database self-protection: If the database has a project_id in metadata,
+     * the CMOS_PROJECT_ID env var MUST be set and match. This prevents
+     * cross-project contamination when multiple projects use CMOS.
+     *
+     * - Database has project_id + env var matches → success
+     * - Database has project_id + env var missing → error (protection active)
+     * - Database has project_id + env var mismatch → error
+     * - Database has no project_id → success (backward compatible)
+     *
+     * @returns CmosToolResult indicating success or mismatch error
+     */
+    validateProjectId(): CmosToolResult<void>;
+}
+/**
+ * Convenience function to create a client and run a single operation
+ *
+ * Automatically closes the connection after the operation.
+ *
+ * @param fn - Function that uses the client
+ * @param options - Client options
+ * @returns Result of the operation
+ */
+export declare function withClient<T>(fn: (client: CmosDatabaseClient) => CmosToolResult<T>, options?: CmosDatabaseClientOptions): Promise<CmosToolResult<T>>;
+/**
+ * Convenience function for async operations with automatic cleanup
+ *
+ * @param fn - Async function that uses the client
+ * @param options - Client options
+ * @returns Result of the operation
+ */
+export declare function withClientAsync<T>(fn: (client: CmosDatabaseClient) => Promise<CmosToolResult<T>>, options?: CmosDatabaseClientOptions): Promise<CmosToolResult<T>>;
+/**
+ * A single entry in a multi-client fan-out result.
+ * Each entry carries the projectRoot that was queried alongside the result.
+ */
+export interface MultiClientEntry<T> {
+    /** The projectRoot that was queried to produce this entry */
+    resolvedFrom: string;
+    /** Whether this instance's query succeeded */
+    success: boolean;
+    /** The query result data (present when success is true) */
+    data?: T;
+    /** Error details (present when success is false) */
+    error?: import('./types').CmosToolError;
+}
+/**
+ * Fan-out a read operation across multiple CMOS instances.
+ *
+ * Runs fn against each projectRoot in parallel. Each result is tagged with
+ * resolvedFrom so callers can attribute results to their source instance.
+ * Partial failures are included in the result array rather than failing the
+ * whole call — the outer success is true as long as the fan-out itself ran.
+ *
+ * @param fn - Async operation to run against each client
+ * @param projectRoots - List of projectRoot paths to fan out across
+ * @returns Success result containing one entry per projectRoot
+ */
+export declare function withMultiClient<T>(fn: (client: CmosDatabaseClient) => Promise<CmosToolResult<T>>, projectRoots: string[]): Promise<CmosToolResult<MultiClientEntry<T>[]>>;
+/**
+ * Return true if toolName+action is a read-only operation eligible for fan-out.
+ *
+ * cmos_agent_onboard is intentionally excluded — it has single-instance
+ * semantics (onboarding one project at a time is correct behavior).
+ *
+ * @param toolName - MCP tool name (e.g. 'cmos_mission')
+ * @param action - Action parameter value (e.g. 'list')
+ */
+export declare function isReadAction(toolName: string, action: string): boolean;
+/**
+ * Convenience function for mutation operations.
+ *
+ * NOTE: Project ID validation has been removed. The explicit projectRoot
+ * requirement (no cwd fallback) provides sufficient protection against
+ * cross-project contamination without requiring env var configuration.
+ *
+ * This function is now identical to withClient but kept for backward
+ * compatibility with existing tool implementations.
+ *
+ * @param fn - Function that uses the client
+ * @param options - Client options
+ * @returns Result of the operation
+ */
+export declare function withClientValidated<T>(fn: (client: CmosDatabaseClient) => CmosToolResult<T>, options?: CmosDatabaseClientOptions): Promise<CmosToolResult<T>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/tools/cmos/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/client.ts"],"names":[],"mappings":"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"}