@negusdev/dbask 0.0.0-stage → 0.1.8

package/dist/core/agent/query-plan.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { RelationshipInfo, SqlDialect, TableInfo, TableSchema } from '../types/index.js';
+/**
+ * The plan the model must submit before it may run SQL. Tables and columns are
+ * structured so they can be checked against the real schema instead of being
+ * free text nobody reads.
+ */
+export declare const queryPlanSchema: z.ZodObject<{
+    objective: z.ZodString;
+    tables: z.ZodArray<z.ZodString>;
+    fields: z.ZodArray<z.ZodObject<{
+        table: z.ZodString;
+        column: z.ZodString;
+    }, z.core.$strip>>;
+    filters: z.ZodArray<z.ZodString>;
+    joins: z.ZodArray<z.ZodObject<{
+        left: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+        }, z.core.$strip>;
+        right: z.ZodObject<{
+            table: z.ZodString;
+            column: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    aggregations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sorting: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Named to avoid clashing with the EXPLAIN `QueryPlan` in core/types. */
+export type StructuredQueryPlan = z.infer<typeof queryPlanSchema>;
+export interface SchemaFacts {
+    dialect: SqlDialect;
+    tables: TableInfo[];
+    relationships: RelationshipInfo[];
+    describe(table: TableInfo): Promise<TableSchema>;
+}
+export interface PlanValidation {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Checks a plan against the live schema: every table exists, every column
+ * exists, fields and joins only touch planned tables, and the planned tables
+ * form one connected join graph (no accidental cross joins). Joins that are not
+ * a declared foreign key are allowed but reported as warnings.
+ */
+export declare function validatePlan(plan: StructuredQueryPlan, facts: SchemaFacts): Promise<PlanValidation>;
+export interface TableReferences {
+    /** Lower-cased bare table names referenced in FROM / JOIN positions. */
+    tables: string[];
+    /** Names defined by WITH clauses; these are not real tables. */
+    ctes: string[];
+}
+/**
+ * Extracts the tables a SELECT reads. Handles quoting, schema qualification,
+ * comma lists, joins, subqueries and CTE names. Returns an empty result when
+ * the SQL cannot be tokenized; the SQL validator reports that failure itself.
+ */
+export declare function extractTableReferences(sql: string, dialect: SqlDialect): TableReferences;
+export interface PlanSqlCheck {
+    ok: boolean;
+    /** Tables used by the SQL that the plan does not list. */
+    unplanned: string[];
+}
+/** The SQL may only read tables that the accepted plan listed. */
+export declare function checkSqlFollowsPlan(sql: string, plan: StructuredQueryPlan, dialect: SqlDialect): PlanSqlCheck;
+//# sourceMappingURL=query-plan.d.ts.map

package/dist/core/agent/query-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-plan.d.ts","sourceRoot":"","sources":["../../../src/core/agent/query-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAO3B;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;iBAmB1B,CAAC;AAEH,0EAA0E;AAC1E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAElE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgBD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,cAAc,CAAC,CA+GzB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAsBD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,eAAe,CAuHxF;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,UAAU,GAClB,YAAY,CAad"}

package/dist/core/agent/query-plan.js

@@ -0,0 +1,282 @@
+import { z } from 'zod';
+import { tokenizeSql } from '../../safety/sql-tokenizer.js';
+const columnRef = z.object({
+    table: z.string().trim().min(1),
+    column: z.string().trim().min(1),
+});
+/**
+ * The plan the model must submit before it may run SQL. Tables and columns are
+ * structured so they can be checked against the real schema instead of being
+ * free text nobody reads.
+ */
+export const queryPlanSchema = z.object({
+    objective: z.string().trim().min(1).max(500),
+    tables: z.array(z.string().trim().min(1)).min(1).max(20),
+    fields: z
+        .array(columnRef)
+        .max(40)
+        .describe('Columns the query reads or returns, each as {table, column}.'),
+    filters: z.array(z.string().trim().min(1)).max(30),
+    joins: z
+        .array(z.object({
+        left: columnRef,
+        right: columnRef,
+    }))
+        .max(20)
+        .describe('One entry per join condition: {left:{table,column}, right:{table,column}}.'),
+    aggregations: z.array(z.string().trim().min(1)).max(20).optional(),
+    sorting: z.array(z.string().trim().min(1)).max(20).optional(),
+});
+const lower = (value) => value.toLowerCase();
+function qualified(table) {
+    return table.schema ? `${table.schema}.${table.name}` : table.name;
+}
+function findTable(tables, name) {
+    const wanted = lower(name);
+    const exact = tables.filter((table) => lower(qualified(table)) === wanted || lower(table.name) === wanted);
+    return exact[0];
+}
+/**
+ * Checks a plan against the live schema: every table exists, every column
+ * exists, fields and joins only touch planned tables, and the planned tables
+ * form one connected join graph (no accidental cross joins). Joins that are not
+ * a declared foreign key are allowed but reported as warnings.
+ */
+export async function validatePlan(plan, facts) {
+    const errors = [];
+    const warnings = [];
+    const resolved = new Map();
+    const unknown = [];
+    for (const name of plan.tables) {
+        const table = findTable(facts.tables, name);
+        if (table)
+            resolved.set(lower(name), table);
+        else
+            unknown.push(name);
+    }
+    if (unknown.length > 0) {
+        errors.push(`Unknown table${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}. Available tables: ${facts.tables.slice(0, 40).map(qualified).join(', ')}${facts.tables.length > 40 ? ', ...' : ''}.`);
+    }
+    const columns = new Map();
+    for (const [key, table] of resolved) {
+        try {
+            const schema = await facts.describe(table);
+            columns.set(key, new Set(schema.columns.map((column) => lower(column.name))));
+        }
+        catch (error) {
+            errors.push(`Could not describe table ${qualified(table)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const checkRef = (ref, where) => {
+        const key = lower(ref.table);
+        if (!resolved.has(key)) {
+            if (!unknown.some((name) => lower(name) === key)) {
+                errors.push(`${where} refers to ${ref.table}.${ref.column}, but ${ref.table} is not listed in "tables".`);
+            }
+            return;
+        }
+        const known = columns.get(key);
+        if (known && !known.has(lower(ref.column))) {
+            errors.push(`${where} refers to ${ref.table}.${ref.column}, but ${ref.table} has no column "${ref.column}".`);
+        }
+    };
+    plan.fields.forEach((field) => checkRef(field, 'Field'));
+    plan.joins.forEach((join) => {
+        checkRef(join.left, 'Join');
+        checkRef(join.right, 'Join');
+    });
+    // Connectivity: every planned table must be reachable through the joins.
+    const parent = new Map();
+    const find = (key) => {
+        let root = key;
+        while (parent.get(root) !== root)
+            root = parent.get(root) ?? root;
+        return root;
+    };
+    for (const key of resolved.keys())
+        parent.set(key, key);
+    for (const join of plan.joins) {
+        const a = lower(join.left.table);
+        const b = lower(join.right.table);
+        if (parent.has(a) && parent.has(b))
+            parent.set(find(a), find(b));
+    }
+    if (resolved.size > 1) {
+        const roots = new Set([...resolved.keys()].map(find));
+        if (roots.size > 1) {
+            const groups = new Map();
+            for (const key of resolved.keys()) {
+                const root = find(key);
+                groups.set(root, [...(groups.get(root) ?? []), key]);
+            }
+            errors.push(`The planned tables are not connected by joins (${[...groups.values()].map((g) => g.join('+')).join(' | ')}). Add the join conditions that connect them, or remove tables the query does not need.`);
+        }
+    }
+    // Joins that are not a declared foreign key: allowed, but flagged.
+    for (const join of plan.joins) {
+        const left = resolved.get(lower(join.left.table));
+        const right = resolved.get(lower(join.right.table));
+        if (!left || !right)
+            continue;
+        const matches = (a, ac, b, bc) => facts.relationships.some((rel) => lower(rel.table) === lower(a.name) &&
+            lower(rel.column) === lower(ac) &&
+            lower(rel.referencedTable) === lower(b.name) &&
+            lower(rel.referencedColumn) === lower(bc));
+        const declared = matches(left, join.left.column, right, join.right.column) ||
+            matches(right, join.right.column, left, join.left.column);
+        if (!declared && facts.relationships.length > 0) {
+            warnings.push(`${join.left.table}.${join.left.column} = ${join.right.table}.${join.right.column} is not a declared foreign key.`);
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+const FROM_END = new Set([
+    'WHERE', 'GROUP', 'ORDER', 'HAVING', 'LIMIT', 'UNION', 'INTERSECT', 'EXCEPT',
+    'ON', 'USING', 'WINDOW', 'OFFSET', 'FETCH', 'FOR', 'JOIN', 'INNER', 'LEFT',
+    'RIGHT', 'FULL', 'CROSS', 'NATURAL',
+]);
+const FROM_FUNCTIONS = new Set(['EXTRACT', 'SUBSTRING', 'TRIM', 'OVERLAY', 'POSITION']);
+function isName(token) {
+    return !!token && (token.type === 'word' || token.type === 'quoted-identifier');
+}
+function bare(token) {
+    const value = token.value;
+    if (token.type === 'quoted-identifier') {
+        return lower(value.slice(1, -1).replace(/""|``/g, (m) => m[0]));
+    }
+    return lower(value);
+}
+/**
+ * Extracts the tables a SELECT reads. Handles quoting, schema qualification,
+ * comma lists, joins, subqueries and CTE names. Returns an empty result when
+ * the SQL cannot be tokenized; the SQL validator reports that failure itself.
+ */
+export function extractTableReferences(sql, dialect) {
+    const { tokens, error } = tokenizeSql(sql, dialect);
+    const empty = { tables: [], ctes: [] };
+    if (error)
+        return empty;
+    const tables = new Set();
+    const ctes = new Set();
+    // Per paren depth: is a FROM list currently open, and is this a function paren.
+    const fromOpen = [false];
+    const functionParen = [false];
+    let depth = 0;
+    const readTableName = (index) => {
+        // Returns the index after the (possibly qualified) name, recording it.
+        const first = tokens[index];
+        if (!isName(first))
+            return index;
+        let last = first;
+        let next = index + 1;
+        while (tokens[next]?.value === '.' && isName(tokens[next + 1])) {
+            last = tokens[next + 1];
+            next += 2;
+        }
+        tables.add(bare(last));
+        return next;
+    };
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'punct') {
+            if (token.value === '(') {
+                const before = tokens[i - 1];
+                depth++;
+                fromOpen[depth] = false;
+                functionParen[depth] = before?.type === 'word' && FROM_FUNCTIONS.has(before.value);
+            }
+            else if (token.value === ')') {
+                fromOpen[depth] = false;
+                depth = Math.max(0, depth - 1);
+            }
+            else if (token.value === ',' && fromOpen[depth] && !functionParen[depth]) {
+                i = readTableName(i + 1) - 1;
+            }
+            continue;
+        }
+        if (token.type !== 'word')
+            continue;
+        if (token.value === 'WITH') {
+            // WITH [RECURSIVE] name [(cols)] AS ( ... ) [, name AS ( ... )]
+            let j = i + 1;
+            if (tokens[j]?.value === 'RECURSIVE')
+                j++;
+            while (isName(tokens[j])) {
+                ctes.add(bare(tokens[j]));
+                j++;
+                if (tokens[j]?.value === '(') {
+                    // optional column list, skip to matching paren
+                    let level = 0;
+                    for (; j < tokens.length; j++) {
+                        if (tokens[j].value === '(')
+                            level++;
+                        if (tokens[j].value === ')' && --level === 0) {
+                            j++;
+                            break;
+                        }
+                    }
+                }
+                if (tokens[j]?.value !== 'AS')
+                    break;
+                j++;
+                if (tokens[j]?.value === 'NOT' || tokens[j]?.value === 'MATERIALIZED')
+                    j++;
+                if (tokens[j]?.value === 'MATERIALIZED')
+                    j++;
+                if (tokens[j]?.value !== '(')
+                    break;
+                let level = 0;
+                for (; j < tokens.length; j++) {
+                    if (tokens[j].value === '(')
+                        level++;
+                    if (tokens[j].value === ')' && --level === 0) {
+                        j++;
+                        break;
+                    }
+                }
+                if (tokens[j]?.value === ',')
+                    j++;
+                else
+                    break;
+            }
+            continue;
+        }
+        if (token.value === 'FROM' || token.value === 'JOIN') {
+            const previous = tokens[i - 1];
+            const isFunctionFrom = functionParen[depth] === true;
+            const isDistinctFrom = previous?.type === 'word' && previous.value === 'DISTINCT';
+            if (isFunctionFrom || isDistinctFrom)
+                continue;
+            if (token.value === 'FROM')
+                fromOpen[depth] = true;
+            // LATERAL and ONLY are modifiers, not names.
+            let next = i + 1;
+            if (tokens[next]?.type === 'word' && (tokens[next].value === 'LATERAL' || tokens[next].value === 'ONLY')) {
+                next++;
+            }
+            if (tokens[next]?.value === '(')
+                continue; // subquery: handled when its own FROM appears
+            i = readTableName(next) - 1;
+            continue;
+        }
+        if (fromOpen[depth] && FROM_END.has(token.value)) {
+            fromOpen[depth] = false;
+        }
+    }
+    return {
+        tables: [...tables].filter((name) => !ctes.has(name)),
+        ctes: [...ctes],
+    };
+}
+/** The SQL may only read tables that the accepted plan listed. */
+export function checkSqlFollowsPlan(sql, plan, dialect) {
+    const planned = new Set(plan.tables.flatMap((table) => {
+        const name = lower(table);
+        const dot = name.lastIndexOf('.');
+        return dot === -1 ? [name] : [name, name.slice(dot + 1)];
+    }));
+    const { tables } = extractTableReferences(sql, dialect);
+    const unplanned = tables.filter((name) => !planned.has(name));
+    return { ok: unplanned.length === 0, unplanned };
+}
+//# sourceMappingURL=query-plan.js.map

package/dist/core/agent/query-plan.js.map

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

package/dist/core/tools/describe-table.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface DescribeTableInput {
+    table: string;
+}
+export declare function describeTable(input: DescribeTableInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=describe-table.d.ts.map

package/dist/core/tools/describe-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-table.d.ts","sourceRoot":"","sources":["../../../src/core/tools/describe-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAyBxB"}

package/dist/core/tools/describe-table.js

@@ -0,0 +1,25 @@
+export async function describeTable(input, context) {
+    const table = input.table.trim();
+    if (!table) {
+        return {
+            success: false,
+            error: 'Table name is required.',
+        };
+    }
+    try {
+        const schema = context.schemaCache
+            ? await context.schemaCache.describeTable(context.database, table)
+            : await context.database.describeTable(table);
+        return {
+            success: true,
+            data: schema,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : `Failed to describe table "${table}".`,
+        };
+    }
+}
+//# sourceMappingURL=describe-table.js.map

package/dist/core/tools/describe-table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-table.js","sourceRoot":"","sources":["../../../src/core/tools/describe-table.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,KAAyB,EACzB,OAAoB;IAEpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAEjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,yBAAyB;SACjC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW;YAChC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC;YAClE,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAEhD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,KAAK,IAAI;SACvF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/describe-tables.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface DescribeTablesInput {
+    tables: string[];
+}
+export declare function describeTables(input: DescribeTablesInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=describe-tables.d.ts.map

package/dist/core/tools/describe-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-tables.d.ts","sourceRoot":"","sources":["../../../src/core/tools/describe-tables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAuBxB"}

package/dist/core/tools/describe-tables.js

@@ -0,0 +1,22 @@
+export async function describeTables(input, context) {
+    const tables = [...new Set((input.tables ?? []).map((table) => table.trim()).filter(Boolean))];
+    if (tables.length === 0) {
+        return { success: false, error: 'At least one table name is required.' };
+    }
+    if (tables.length > 10) {
+        return { success: false, error: 'A maximum of 10 tables can be described at once.' };
+    }
+    try {
+        const schemas = context.schemaCache
+            ? await context.schemaCache.describeTables(context.database, tables)
+            : await Promise.all(tables.map((table) => context.database.describeTable(table)));
+        return { success: true, data: schemas };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to describe tables.',
+        };
+    }
+}
+//# sourceMappingURL=describe-tables.js.map

package/dist/core/tools/describe-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-tables.js","sourceRoot":"","sources":["../../../src/core/tools/describe-tables.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,KAA0B,EAC1B,OAAoB;IAEpB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/F,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;IAC3E,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,kDAAkD,EAAE,CAAC;IACvF,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW;YACjC,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC;YACpE,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAEpF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,4BAA4B;SAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/execute-query.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface ExecuteQueryInput {
+    sql: string;
+}
+export declare function executeQuery(input: ExecuteQueryInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=execute-query.d.ts.map

package/dist/core/tools/execute-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-query.d.ts","sourceRoot":"","sources":["../../../src/core/tools/execute-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/core/tools/execute-query.js

@@ -0,0 +1,31 @@
+import { validateSql } from '../../safety/sql-validator.js';
+export async function executeQuery(input, context) {
+    const validation = validateSql(input.sql, context.safety, context.database.dialect);
+    if (!validation.valid || !validation.sql) {
+        return {
+            success: false,
+            executionAttempted: false,
+            error: validation.reason ?? 'SQL query failed validation.',
+        };
+    }
+    try {
+        const result = await context.database.executeQuery(validation.sql, {
+            maxRows: context.safety.maxRows,
+            timeoutMs: context.safety.queryTimeoutMs,
+            maxResultBytes: context.safety.maxResultBytes,
+        });
+        return {
+            success: true,
+            executionAttempted: true,
+            data: result,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            executionAttempted: true,
+            error: error instanceof Error ? error.message : 'Failed to execute query.',
+        };
+    }
+}
+//# sourceMappingURL=execute-query.js.map

package/dist/core/tools/execute-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-query.js","sourceRoot":"","sources":["../../../src/core/tools/execute-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAM5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,OAAoB;IAEpB,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEpF,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACzC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,kBAAkB,EAAE,KAAK;YACzB,KAAK,EAAE,UAAU,CAAC,MAAM,IAAI,8BAA8B;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE;YACjE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc;YACxC,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc;SAC9C,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,IAAI;YACb,kBAAkB,EAAE,IAAI;YACxB,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,kBAAkB,EAAE,IAAI;YACxB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B;SAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/explain-query.d.ts

@@ -0,0 +1,10 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface ExplainQueryInput {
+    sql: string;
+}
+/**
+ * Produces a database query plan after passing the SQL through the harness
+ * safety boundary.
+ */
+export declare function explainQuery(input: ExplainQueryInput, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=explain-query.d.ts.map

package/dist/core/tools/explain-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-query.d.ts","sourceRoot":"","sources":["../../../src/core/tools/explain-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGpE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/core/tools/explain-query.js

@@ -0,0 +1,34 @@
+import { validateSql } from '../../safety/sql-validator.js';
+/**
+ * Produces a database query plan after passing the SQL through the harness
+ * safety boundary.
+ */
+export async function explainQuery(input, context) {
+    const validation = validateSql(input.sql, context.safety, context.database.dialect);
+    if (!validation.valid || !validation.sql) {
+        return {
+            success: false,
+            error: validation.reason ?? 'SQL query failed validation.',
+        };
+    }
+    if (!/^(SELECT|WITH)\b/i.test(validation.sql)) {
+        return {
+            success: false,
+            error: 'Only SELECT or WITH queries can be explained by this tool.',
+        };
+    }
+    try {
+        const result = await context.database.explainQuery(validation.sql);
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to explain query.',
+        };
+    }
+}
+//# sourceMappingURL=explain-query.js.map

package/dist/core/tools/explain-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-query.js","sourceRoot":"","sources":["../../../src/core/tools/explain-query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAM5D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAwB,EACxB,OAAoB;IAEpB,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAEpF,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;QACzC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,UAAU,CAAC,MAAM,IAAI,8BAA8B;SAC3D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,4DAA4D;SACpE,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAEnE,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM;SACb,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B;SAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/get-relationships.d.ts

@@ -0,0 +1,6 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export interface GetRelationshipsInput {
+    table?: string;
+}
+export declare function getRelationships(input: GetRelationshipsInput | undefined, context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=get-relationships.d.ts.map

package/dist/core/tools/get-relationships.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-relationships.d.ts","sourceRoot":"","sources":["../../../src/core/tools/get-relationships.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,qBAAqB,YAAK,EACjC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/core/tools/get-relationships.js

@@ -0,0 +1,23 @@
+export async function getRelationships(input = {}, context) {
+    const table = input.table?.trim() || undefined;
+    try {
+        const relationships = table
+            ? await context.database.getRelationships(table)
+            : context.schemaCache
+                ? await context.schemaCache.getRelationships(context.database)
+                : await context.database.getRelationships();
+        return {
+            success: true,
+            data: relationships,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error
+                ? error.message
+                : 'Failed to retrieve database relationships.',
+        };
+    }
+}
+//# sourceMappingURL=get-relationships.js.map

package/dist/core/tools/get-relationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-relationships.js","sourceRoot":"","sources":["../../../src/core/tools/get-relationships.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAK,GAA0B,EAAE,EACjC,OAAoB;IAEpB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAE/C,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,KAAK;YACzB,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,CAAC;YAChD,CAAC,CAAC,OAAO,CAAC,WAAW;gBACnB,CAAC,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC9D,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QAEhD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,aAAa;SACpB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK;gBAC3B,CAAC,CAAC,KAAK,CAAC,OAAO;gBACf,CAAC,CAAC,4CAA4C;SACjD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/tools/index.d.ts

@@ -0,0 +1,9 @@
+export { listTables } from './list-tables.js';
+export { describeTable } from './describe-table.js';
+export { describeTables } from './describe-tables.js';
+export { getRelationships } from './get-relationships.js';
+export { executeQuery } from './execute-query.js';
+export { explainQuery } from './explain-query.js';
+export { getTool, getTools, executeTool } from './registry.js';
+export type { ToolName, RegisteredTool } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/tools/index.js

@@ -0,0 +1,8 @@
+export { listTables } from './list-tables.js';
+export { describeTable } from './describe-table.js';
+export { describeTables } from './describe-tables.js';
+export { getRelationships } from './get-relationships.js';
+export { executeQuery } from './execute-query.js';
+export { explainQuery } from './explain-query.js';
+export { getTool, getTools, executeTool } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/core/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/tools/list-tables.d.ts

@@ -0,0 +1,3 @@
+import type { SqlToolResult, ToolContext } from '../types/index.js';
+export declare function listTables(context: ToolContext): Promise<SqlToolResult>;
+//# sourceMappingURL=list-tables.d.ts.map