cgraphx 1.1.0

package/dist/dbquery/queries.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * SQL query templates for the schema-introspection modes (spec §4.2).
+ *
+ * Each function returns either a SQL string (for parameterless queries) or
+ * an object `{ sql, params }` for parameterized queries. Parameter binding
+ * is mandatory — never string-concat user-supplied identifiers.
+ *
+ * Parameter style:
+ *   - MySQL:  uses `?` placeholders (mysql2)
+ *   - PG:     uses `$1, $2, ...` placeholders (pg)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mysqlTablesSql = mysqlTablesSql;
+exports.mysqlDdlSql = mysqlDdlSql;
+exports.mysqlPrimaryKeySql = mysqlPrimaryKeySql;
+exports.mysqlConstraintsSql = mysqlConstraintsSql;
+exports.mysqlIndexesSql = mysqlIndexesSql;
+exports.mysqlTableCommentSql = mysqlTableCommentSql;
+exports.postgresTablesSql = postgresTablesSql;
+exports.postgresDdlSql = postgresDdlSql;
+exports.postgresPrimaryKeySql = postgresPrimaryKeySql;
+exports.postgresConstraintsSql = postgresConstraintsSql;
+exports.postgresIndexesSql = postgresIndexesSql;
+exports.postgresTableCommentSql = postgresTableCommentSql;
+exports.mysqlSchemaQuery = mysqlSchemaQuery;
+exports.postgresSchemaQuery = postgresSchemaQuery;
+// ─── MySQL (information_schema) ───
+function mysqlTablesSql(database) {
+    return {
+        sql: 'SELECT TABLE_NAME AS name, TABLE_COMMENT AS comment ' +
+            'FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME',
+        params: [database],
+    };
+}
+function mysqlDdlSql(table, database) {
+    return {
+        sql: 'SELECT COLUMN_NAME AS name, COLUMN_TYPE AS data_type, IS_NULLABLE AS nullable, ' +
+            'COLUMN_DEFAULT AS default_value, COLUMN_COMMENT AS comment ' +
+            'FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? ' +
+            'ORDER BY ORDINAL_POSITION',
+        params: [database, table],
+    };
+}
+function mysqlPrimaryKeySql(table, database) {
+    return {
+        sql: 'SELECT COLUMN_NAME AS column_name ' +
+            'FROM information_schema.KEY_COLUMN_USAGE ' +
+            'WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? AND CONSTRAINT_NAME = \'PRIMARY\' ' +
+            'ORDER BY ORDINAL_POSITION',
+        params: [database, table],
+    };
+}
+function mysqlConstraintsSql(table, database) {
+    return {
+        sql: 'SELECT CONSTRAINT_NAME AS name, CONSTRAINT_TYPE AS type ' +
+            'FROM information_schema.TABLE_CONSTRAINTS ' +
+            'WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?',
+        params: [database, table],
+    };
+}
+function mysqlIndexesSql(table, database) {
+    return {
+        sql: 'SELECT INDEX_NAME AS name, COLUMN_NAME AS column_name, NON_UNIQUE = 0 AS is_unique, ' +
+            'INDEX_TYPE AS type, SEQ_IN_INDEX AS seq ' +
+            'FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? ' +
+            'ORDER BY INDEX_NAME, SEQ_IN_INDEX',
+        params: [database, table],
+    };
+}
+function mysqlTableCommentSql(table, database) {
+    return {
+        sql: 'SELECT TABLE_COMMENT AS comment FROM information_schema.TABLES ' +
+            'WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?',
+        params: [database, table],
+    };
+}
+// ─── PostgreSQL (pg_catalog) ───
+function postgresTablesSql(schema) {
+    return {
+        sql: 'SELECT c.relname AS name, ' +
+            'COALESCE(obj_description(c.oid), \'\') AS comment ' +
+            'FROM pg_class c ' +
+            'JOIN pg_namespace n ON n.oid = c.relnamespace ' +
+            'WHERE c.relkind IN (\'r\', \'p\') AND n.nspname = $1 ' +
+            'ORDER BY c.relname',
+        params: [schema],
+    };
+}
+function postgresDdlSql(table, schema) {
+    return {
+        sql: 'SELECT a.attname AS name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS data_type, ' +
+            'NOT a.attnotnull AS nullable, pg_get_expr(d.adbin, d.adrelid) AS default_value, ' +
+            'COALESCE(col_description(a.attrelid, a.attnum), \'\') AS comment ' +
+            'FROM pg_attribute a ' +
+            'LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum ' +
+            'WHERE a.attrelid = $1::regclass AND a.attnum > 0 AND NOT a.attisdropped ' +
+            'ORDER BY a.attnum',
+        params: [`${schema}.${table}`],
+    };
+}
+function postgresPrimaryKeySql(table, schema) {
+    return {
+        sql: 'SELECT a.attname AS column_name ' +
+            'FROM pg_index i ' +
+            'JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey) ' +
+            'WHERE i.indrelid = $1::regclass AND i.indisprimary ' +
+            'ORDER BY array_position(i.indkey, a.attnum)',
+        params: [`${schema}.${table}`],
+    };
+}
+function postgresConstraintsSql(table, schema) {
+    return {
+        sql: 'SELECT c.conname AS name, ' +
+            'CASE WHEN c.contype = \'p\' THEN \'PRIMARY KEY\' ' +
+            'WHEN c.contype = \'u\' THEN \'UNIQUE\' ' +
+            'WHEN c.contype = \'f\' THEN \'FOREIGN KEY\' ' +
+            'WHEN c.contype = \'c\' THEN \'CHECK\' ELSE c.contype::text END AS type ' +
+            'FROM pg_constraint c ' +
+            'WHERE c.conrelid = $1::regclass ORDER BY c.conname',
+        params: [`${schema}.${table}`],
+    };
+}
+function postgresIndexesSql(table, schema) {
+    return {
+        sql: 'SELECT i.relname AS name, ' +
+            'array_to_string(ARRAY(SELECT pg_get_indexdef(ix.indexrelid, k + 1, true) ' +
+            'FROM generate_subscripts(ix.indkey, 1) AS k), \',\') AS columns_csv, ' +
+            'ix.indisunique AS is_unique, am.amname AS type ' +
+            'FROM pg_index ix ' +
+            'JOIN pg_class i ON i.oid = ix.indexrelid ' +
+            'JOIN pg_class t ON t.oid = ix.indrelid ' +
+            'JOIN pg_am am ON am.oid = i.relam ' +
+            'WHERE ix.indrelid = $1::regclass ORDER BY i.relname',
+        params: [`${schema}.${table}`],
+    };
+}
+function postgresTableCommentSql(table, schema) {
+    return {
+        sql: 'SELECT COALESCE(obj_description($1::regclass), \'\') AS comment',
+        params: [`${schema}.${table}`],
+    };
+}
+function mysqlSchemaQuery(mode, table, database) {
+    switch (mode) {
+        case 'tables': return mysqlTablesSql(database);
+        case 'ddl': return mysqlDdlSql(table, database);
+        case 'indexes': return mysqlIndexesSql(table, database);
+        case 'table-comment': return mysqlTableCommentSql(table, database);
+    }
+}
+function postgresSchemaQuery(mode, table, schema) {
+    switch (mode) {
+        case 'tables': return postgresTablesSql(schema);
+        case 'ddl': return postgresDdlSql(table, schema);
+        case 'indexes': return postgresIndexesSql(table, schema);
+        case 'table-comment': return postgresTableCommentSql(table, schema);
+    }
+}
+//# sourceMappingURL=queries.js.map

package/dist/dbquery/queries.js.map

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

package/dist/dbquery/safety.d.ts

@@ -0,0 +1,35 @@
+/**
+ * SQL safety checks for the db-query subsystem.
+ *
+ * Single responsibility: take a raw SQL string and either (a) approve it with
+ * a normalized form and a final LIMIT, or (b) reject it with a structured
+ * SafetyRejectionError. All write operations must be blocked — see spec §3.
+ *
+ * Layering:
+ *   1. strip comments (block comments with nesting, plus -- and # line comments)
+ *      while preserving string literals (so 'INSERT' still trips detection)
+ *   2. multi-statement check (any `;` after stripping → reject)
+ *   3. forbidden keyword scan (case-insensitive, word-boundary)
+ *   4. LIMIT enforcement (SELECT only; schema queries pass through)
+ */
+import { SafetyRejectionError } from './errors';
+export interface SafetyOk {
+    ok: true;
+    normalizedSql: string;
+    effectiveLimit: number;
+    modified: boolean;
+}
+export interface SafetyFail {
+    ok: false;
+    normalizedSql: string;
+    error: SafetyRejectionError;
+}
+export type SafetyResult = SafetyOk | SafetyFail;
+/**
+ * Main entry point. Performs all safety checks.
+ *
+ * Returns SafetyOk if the query is approved, SafetyFail otherwise. Never
+ * throws — callers branching on `.ok` get full type narrowing.
+ */
+export declare function checkSafety(rawSql: string, requestedLimit?: number): SafetyResult;
+//# sourceMappingURL=safety.d.ts.map

package/dist/dbquery/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../src/dbquery/safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEhD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AA6PjD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,GACtB,YAAY,CA4Cd"}

package/dist/dbquery/safety.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * SQL safety checks for the db-query subsystem.
+ *
+ * Single responsibility: take a raw SQL string and either (a) approve it with
+ * a normalized form and a final LIMIT, or (b) reject it with a structured
+ * SafetyRejectionError. All write operations must be blocked — see spec §3.
+ *
+ * Layering:
+ *   1. strip comments (block comments with nesting, plus -- and # line comments)
+ *      while preserving string literals (so 'INSERT' still trips detection)
+ *   2. multi-statement check (any `;` after stripping → reject)
+ *   3. forbidden keyword scan (case-insensitive, word-boundary)
+ *   4. LIMIT enforcement (SELECT only; schema queries pass through)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSafety = checkSafety;
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+/**
+ * Strip SQL comments while preserving string literals (so a keyword like
+ * 'INSERT' inside a string still trips the keyword scan — defense in depth,
+ * spec §3.2 铁律).
+ *
+ * Comment forms handled:
+ *   - block: `/* ... *\/` with nesting (MySQL syntax; PG doesn't nest but we
+ *     handle it conservatively)
+ *   - line:  `-- ...` and `# ...` (MySQL) up to end of line
+ *
+ * Comments are replaced with single spaces (line/column preservation for
+ * error reporting).
+ */
+function stripComments(sql) {
+    let out = '';
+    let i = 0;
+    const n = sql.length;
+    let state = 'normal';
+    let blockDepth = 0;
+    while (i < n) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        switch (state) {
+            case 'normal': {
+                if (ch === "'") {
+                    out += ch;
+                    state = 'single';
+                    i++;
+                }
+                else if (ch === '"') {
+                    out += ch;
+                    state = 'double';
+                    i++;
+                }
+                else if (ch === '/' && next === '*') {
+                    out += ' ';
+                    i += 2;
+                    state = 'block';
+                    blockDepth = 1;
+                }
+                else if (ch === '-' && next === '-') {
+                    out += ' ';
+                    i += 2;
+                    state = 'line';
+                }
+                else if (ch === '#') {
+                    out += ' ';
+                    i++;
+                    state = 'line';
+                }
+                else {
+                    out += ch;
+                    i++;
+                }
+                break;
+            }
+            case 'single': {
+                if (ch === "'") {
+                    // MySQL/PG both escape ' as ''
+                    if (next === "'") {
+                        out += "''";
+                        i += 2;
+                    }
+                    else {
+                        out += ch;
+                        state = 'normal';
+                        i++;
+                    }
+                }
+                else {
+                    out += ch;
+                    i++;
+                }
+                break;
+            }
+            case 'double': {
+                if (ch === '"') {
+                    out += ch;
+                    state = 'normal';
+                    i++;
+                }
+                else {
+                    out += ch;
+                    i++;
+                }
+                break;
+            }
+            case 'block': {
+                if (ch === '/' && next === '*') {
+                    // nested — MySQL allows; we count depth
+                    blockDepth++;
+                    i += 2;
+                }
+                else if (ch === '*' && next === '/') {
+                    blockDepth--;
+                    i += 2;
+                    if (blockDepth === 0) {
+                        state = 'normal';
+                    }
+                }
+                else if (ch === '\n') {
+                    // preserve newlines so multi-line comments don't collapse lines
+                    out += '\n';
+                    i++;
+                }
+                else {
+                    i++;
+                }
+                break;
+            }
+            case 'line': {
+                if (ch === '\n') {
+                    out += '\n';
+                    state = 'normal';
+                    i++;
+                }
+                else {
+                    i++;
+                }
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Find forbidden keywords in the (already comment-stripped) SQL.
+ * Case-insensitive, word-boundary matched. Returns matched keywords (deduped).
+ */
+function findForbiddenKeywords(sql) {
+    const matched = new Set();
+    for (const kw of constants_1.FORBIDDEN_KEYWORDS) {
+        // \b boundary handles word edges; case-insensitive.
+        // MySQL backtick-quoted identifiers: `INSERT` is a table name, but we
+        // still reject it defensively (spec §3.1 last bullet).
+        const re = new RegExp(`(^|[^A-Za-z0-9_])${escapeRegex(kw)}(?![A-Za-z0-9_])`, 'i');
+        if (re.test(sql)) {
+            matched.add(kw);
+        }
+    }
+    return Array.from(matched);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Multi-statement check: any semicolon in the comment-stripped SQL rejects.
+ * Single-statement-only is the contract (spec §3.3).
+ *
+ * Trailing `;` or `;   ` also rejected (spec §3.3).
+ */
+function hasMultipleStatements(sql) {
+    // Semicolons inside string literals are preserved by stripComments, so they
+    // still trigger this — which is correct (a string literal with `;` is rare
+    // and the defensive choice is to reject).
+    return sql.includes(';');
+}
+/**
+ * Detect whether this query should bypass LIMIT enforcement.
+ * Spec §3.4: SHOW / DESCRIBE / EXPLAIN / information_schema.* / pg_catalog.*
+ * are schema queries — they return small fixed result sets.
+ *
+ * Anything that's not a `SELECT` (USE / SET / etc.) also bypasses — drivers
+ * will reject most non-SELECT statements anyway, and our keyword blacklist
+ * already blocks writes.
+ */
+function isSchemaQuery(sql) {
+    const trimmed = sql.trimStart().toUpperCase();
+    if (!trimmed.startsWith('SELECT')) {
+        return true;
+    }
+    return informationSchemaQuery(sql);
+}
+/**
+ * True if this SELECT queries information_schema or pg_catalog — those return
+ * small fixed result sets and never need LIMIT forced.
+ */
+function informationSchemaQuery(sql) {
+    const lower = sql.toLowerCase();
+    return (lower.includes('information_schema') ||
+        lower.includes('pg_catalog') ||
+        lower.includes('pg_attribute') ||
+        lower.includes('pg_class') ||
+        lower.includes('pg_index') ||
+        lower.includes('pg_indexes') ||
+        lower.includes('pg_description') ||
+        lower.includes('pg_namespace'));
+}
+/**
+ * Detect and parse existing LIMIT clause. Returns the limit value if present.
+ */
+function detectExistingLimit(sql) {
+    // Match `LIMIT <number>` or `limit <number>` near end of query.
+    // We don't try to handle OFFSET or subqueries — just a top-level LIMIT.
+    const m = sql.match(/\blimit\s+(\d+)\b/i);
+    return m && m[1] ? parseInt(m[1], 10) : null;
+}
+/**
+ * Normalize whitespace: collapse runs of whitespace into single spaces,
+ * preserving newlines as-is. The output is what's logged + returned in errors.
+ */
+function normalizeWhitespace(sql) {
+    return sql
+        .split('\n')
+        .map(line => line.replace(/[ \t]+/g, ' ').trim())
+        .join('\n')
+        .trim();
+}
+/**
+ * Wrap or rewrite the SELECT with the final LIMIT.
+ *
+ * Spec §3.4 matrix:
+ *   - no LIMIT          → append ` LIMIT N` (default 100, or requestedLimit)
+ *   - LIMIT ≤ cap       → unchanged
+ *   - LIMIT > cap       → rewrite down to cap (1000)
+ *
+ * For schema queries, returns SQL unchanged (no LIMIT added).
+ */
+function enforceLimit(sql, requestedLimit) {
+    if (informationSchemaQuery(sql)) {
+        return { sql, effectiveLimit: 0, modified: false };
+    }
+    const existing = detectExistingLimit(sql);
+    if (existing !== null) {
+        if (existing > constants_1.MAX_LIMIT) {
+            const rewritten = sql.replace(new RegExp(`\\blimit\\s+\\d+`, 'i'), `LIMIT ${constants_1.MAX_LIMIT}`);
+            return { sql: rewritten, effectiveLimit: constants_1.MAX_LIMIT, modified: true };
+        }
+        return { sql, effectiveLimit: existing, modified: false };
+    }
+    // No existing LIMIT — append.
+    const finalLimit = requestedLimit !== undefined
+        ? Math.min(requestedLimit, constants_1.MAX_LIMIT)
+        : constants_1.DEFAULT_LIMIT;
+    return {
+        sql: `${sql.replace(/;\s*$/, '')} LIMIT ${finalLimit}`,
+        effectiveLimit: finalLimit,
+        modified: true,
+    };
+}
+/**
+ * Main entry point. Performs all safety checks.
+ *
+ * Returns SafetyOk if the query is approved, SafetyFail otherwise. Never
+ * throws — callers branching on `.ok` get full type narrowing.
+ */
+function checkSafety(rawSql, requestedLimit) {
+    const stripped = stripComments(rawSql);
+    const normalizedSql = normalizeWhitespace(stripped);
+    // 1. Empty SQL
+    if (normalizedSql.length === 0) {
+        return {
+            ok: false,
+            normalizedSql,
+            error: new errors_1.SafetyRejectionError(['(empty)'], normalizedSql),
+        };
+    }
+    // 2. Multi-statement
+    if (hasMultipleStatements(normalizedSql)) {
+        return {
+            ok: false,
+            normalizedSql,
+            error: new errors_1.SafetyRejectionError([';'], normalizedSql),
+        };
+    }
+    // 3. Forbidden keyword scan
+    const matched = findForbiddenKeywords(normalizedSql);
+    if (matched.length > 0) {
+        return {
+            ok: false,
+            normalizedSql,
+            error: new errors_1.SafetyRejectionError(matched, normalizedSql),
+        };
+    }
+    // 4. LIMIT enforcement (skipped for schema queries)
+    if (isSchemaQuery(normalizedSql)) {
+        return { ok: true, normalizedSql, effectiveLimit: 0, modified: false };
+    }
+    const limited = enforceLimit(normalizedSql, requestedLimit);
+    return {
+        ok: true,
+        normalizedSql: limited.sql,
+        effectiveLimit: limited.effectiveLimit,
+        modified: limited.modified,
+    };
+}
+//# sourceMappingURL=safety.js.map

package/dist/dbquery/safety.js.map

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

package/dist/dbquery/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Type definitions for the db-query subsystem.
+ *
+ * Isolated from codegraph's main `src/types.ts` (NodeKind / EdgeKind) — the
+ * db-query subsystem never touches the code graph. See
+ * `docs/features/2026-06-26-db-query-integration/spec.md` §0.1.
+ */
+export type DriverKind = 'mysql' | 'postgres';
+export type QueryMode = 'query' | 'tables' | 'ddl' | 'indexes' | 'table-comment' | 'profiles';
+export type QueryStatus = 'ok' | 'safety-rejected' | 'config-error' | 'connection-failed' | 'timeout' | 'driver-error' | 'disabled';
+export interface DBProfile {
+    name: string;
+    description?: string;
+    type: DriverKind;
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    /** PostgreSQL only; defaults to 'public'. */
+    schema?: string;
+}
+export type ConfigSource = 'env' | 'project-local' | 'user-global';
+export interface ProfilesConfig {
+    profiles: DBProfile[];
+    defaultProfile: string | null;
+    sources: ConfigSource[];
+    enabled: boolean;
+}
+export interface ProfileEntry {
+    description?: string;
+    type: DriverKind;
+    host: string;
+    port?: number;
+    user: string;
+    password: string;
+    database: string;
+    schema?: string;
+}
+export type ProfilesFile = {
+    default?: string;
+    enabled?: boolean;
+    [profile: string]: ProfileEntry | string | boolean | undefined;
+};
+export interface QueryInput {
+    sql: string;
+    profile?: string;
+    limit?: number;
+}
+export interface QueryColumn {
+    name: string;
+    dataType?: string;
+}
+export interface QueryResult {
+    columns: QueryColumn[];
+    rows: Record<string, unknown>[];
+    rowCount: number;
+    truncated: boolean;
+    profile: string;
+    durationMs: number;
+}
+export interface SchemaInput {
+    mode: 'tables' | 'ddl' | 'indexes' | 'table-comment';
+    table?: string;
+    profile?: string;
+}
+export interface TableSummary {
+    name: string;
+    comment?: string;
+}
+export interface ColumnDefinition {
+    name: string;
+    dataType: string;
+    nullable: boolean;
+    defaultValue?: string;
+    comment?: string;
+}
+export interface ConstraintDefinition {
+    name: string;
+    type: string;
+    columns: string[];
+}
+export interface DdlResult {
+    table: string;
+    columns: ColumnDefinition[];
+    primaryKey: string[];
+    constraints: ConstraintDefinition[];
+    profile: string;
+    durationMs: number;
+}
+export interface IndexDefinition {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    type?: string;
+}
+export interface IndexesResult {
+    table: string;
+    indexes: IndexDefinition[];
+    profile: string;
+    durationMs: number;
+}
+export interface TableCommentResult {
+    table: string;
+    comment: string | null;
+    profile: string;
+    durationMs: number;
+}
+export interface TablesResult {
+    tables: TableSummary[];
+    profile: string;
+    durationMs: number;
+}
+export type SchemaResult = TablesResult | DdlResult | IndexesResult | TableCommentResult;
+export interface ProfilesResult {
+    profiles: Array<{
+        name: string;
+        description?: string;
+        type: DriverKind;
+        host: string;
+        port: number;
+        database: string;
+        hasCredentials: boolean;
+    }>;
+    defaultProfile: string | null;
+    configSources: ConfigSource[];
+    enabled: boolean;
+}
+export interface ProfilesInput {
+    /** Force a specific project root; otherwise resolved by config layer. */
+    projectRoot?: string;
+}
+export interface QueryLogRecord {
+    timestamp: string;
+    profile: string;
+    mode: QueryMode;
+    sql?: string;
+    durationMs: number;
+    rowCount?: number;
+    truncated?: boolean;
+    status: QueryStatus;
+    errorMessage?: string;
+}
+export interface RawResult {
+    columns: QueryColumn[];
+    rows: Record<string, unknown>[];
+}
+export interface DriverConnection {
+    execute(sql: string, timeoutMs: number, params?: unknown[]): Promise<RawResult>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map