@deepagents/text2sql 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -10,5 +10,6 @@ export * from './lib/fragments/schema.ts';
 export * from './lib/fs/index.ts';
 export * from './lib/instructions.ts';
 export * from './lib/sql-hooks.ts';
+export { type CreateSqlCommandOptions, type CreateSqlCommandResult, createSqlCommand, } from './lib/sql-command.ts';
 export * from './lib/sql.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -189,6 +189,13 @@ function createGroundingContext(options = {}) {
 import nodeSqlParser from "node-sql-parser";
 var { Parser } = nodeSqlParser;
 var parser = new Parser();
+function parseStatementTypes(sql, dialect) {
+  const ast = parser.astify(sql, { database: dialect });
+  const statements = Array.isArray(ast) ? ast : [ast];
+  return statements.flatMap(
+    (statement) => isAstLike(statement) && typeof statement.type === "string" ? [statement.type] : []
+  );
+}
 function extractBaseEntityReferences(sql, dialect) {
   const ast = parser.astify(sql, { database: dialect });
   const state = {
@@ -314,6 +321,22 @@ function caseFold(value) {
 }
 
 // packages/text2sql/src/lib/adapters/adapter.ts
+var PARSER_DIALECTS_BY_FORMATTER_LANGUAGE = {
+  sqlite: ["sqlite", "mysql"],
+  postgresql: ["postgresql"],
+  bigquery: ["bigquery"],
+  transactsql: ["transactsql"],
+  mysql: ["mysql"]
+};
+function parserDialectsFor(formatterLanguage) {
+  const candidates = PARSER_DIALECTS_BY_FORMATTER_LANGUAGE[formatterLanguage];
+  if (!candidates) {
+    throw new TypeError(
+      `No scope dialect mapping for formatter language "${formatterLanguage}". Add it to PARSER_DIALECTS_BY_FORMATTER_LANGUAGE in adapter.ts.`
+    );
+  }
+  return candidates;
+}
 var Adapter = class {
   /**
    * Introspect the database schema and return context fragments.
@@ -535,10 +558,49 @@ var Adapter = class {
     return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*])/g, "$1").replace(/\\(?=$)/gm, "");
   }
   #checkReadOnly(sql) {
-    const upper = sql.trimStart().toUpperCase();
-    if (!upper.startsWith("SELECT") && !upper.startsWith("WITH")) {
+    const statementTypes = this.#readParsedStatementTypes(sql);
+    if (statementTypes) {
+      if (statementTypes.length === 1 && statementTypes[0] === "select") {
+        return null;
+      }
       return "only SELECT or WITH queries allowed";
     }
+    const keyword = this.#firstStatementKeyword(sql);
+    if (keyword === "SELECT" || keyword === "WITH") return null;
+    return "only SELECT or WITH queries allowed";
+  }
+  #readParsedStatementTypes(sql) {
+    for (const dialect of parserDialectsFor(this.formatterLanguage)) {
+      try {
+        return parseStatementTypes(sql, dialect);
+      } catch {
+      }
+    }
+    return null;
+  }
+  #firstStatementKeyword(sql) {
+    let offset = 0;
+    while (offset < sql.length) {
+      if (/\s/.test(sql[offset])) {
+        offset++;
+        continue;
+      }
+      if (sql.startsWith("--", offset)) {
+        offset += 2;
+        while (offset < sql.length && sql[offset] !== "\n" && sql[offset] !== "\r") {
+          offset++;
+        }
+        continue;
+      }
+      if (sql.startsWith("/*", offset)) {
+        const commentEnd = sql.indexOf("*/", offset + 2);
+        if (commentEnd === -1) return null;
+        offset = commentEnd + 2;
+        continue;
+      }
+      const keyword = /^[A-Za-z]+/.exec(sql.slice(offset));
+      return keyword ? keyword[0].toUpperCase() : null;
+    }
     return null;
   }
   #cachedAllowedEntities = null;
@@ -548,36 +610,21 @@ var Adapter = class {
     return this.#cachedAllowedEntities;
   }
   async #checkScope(sql, allowedEntities) {
-    const dialect = this.formatterLanguage;
-    const scopeDialects = {
-      sqlite: ["sqlite", "mysql"],
-      postgresql: ["postgresql"],
-      bigquery: ["bigquery"],
-      transactsql: ["transactsql"],
-      mysql: ["mysql"]
-    };
-    const candidates = scopeDialects[dialect];
-    if (!candidates) {
-      throw new TypeError(
-        `No scope dialect mapping for formatter language "${dialect}". Add it to the scopeDialects map in Adapter.#checkScope.`
-      );
-    }
+    const candidates = parserDialectsFor(this.formatterLanguage);
     let references = null;
     let lastError;
+    let lastDialect = candidates[0];
     for (const candidate of candidates) {
       try {
         references = extractBaseEntityReferences(sql, candidate);
         break;
       } catch (error) {
+        lastDialect = candidate;
         lastError = error;
       }
     }
     if (references === null) {
-      return buildScopeParseErrorPayload(
-        sql,
-        dialect,
-        lastError
-      );
+      return buildScopeParseErrorPayload(sql, lastDialect, lastError);
     }
     if (references.length === 0) return null;
     const allowedQualified = new Set(
@@ -5478,8 +5525,48 @@ function createSqlCommandHooks({
   };
 }
 
+// packages/text2sql/src/lib/sql-command.ts
+import { posix as posix5 } from "node:path";
+import { parseArgs } from "node:util";
+import { v7 } from "uuid";
+import {
+  buildSubcommandRepair as buildSubcommandRepair2,
+  defineSubcommandGroup,
+  repairQuotedArg as repairQuotedArg2,
+  useBashMeta as useBashMeta2
+} from "@deepagents/context";
+
 // packages/text2sql/src/lib/sql.ts
 import "@deepagents/agent";
+var text2SqlValidationMarker = Symbol("Text2SqlValidationError");
+var text2SqlUnknownAdapterMarker = Symbol("Text2SqlUnknownAdapterError");
+var Text2SqlValidationError = class _Text2SqlValidationError extends Error {
+  [text2SqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "Text2SqlValidationError";
+    this[text2SqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _Text2SqlValidationError && error[text2SqlValidationMarker] === true;
+  }
+};
+var Text2SqlUnknownAdapterError = class _Text2SqlUnknownAdapterError extends Error {
+  [text2SqlUnknownAdapterMarker];
+  adapter;
+  available;
+  constructor(adapter, available) {
+    const list = available.join(", ") || "(none configured)";
+    super(`Unknown adapter "${adapter}". Available: ${list}`);
+    this.name = "Text2SqlUnknownAdapterError";
+    this.adapter = adapter;
+    this.available = available;
+    this[text2SqlUnknownAdapterMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _Text2SqlUnknownAdapterError && error[text2SqlUnknownAdapterMarker] === true;
+  }
+};
 var Text2Sql = class {
   #config;
   #indexer;
@@ -5498,19 +5585,59 @@ var Text2Sql = class {
   #requireAdapter(name) {
     const adapter = this.#config.adapters[name];
     if (!adapter) {
-      const available = Object.keys(this.#config.adapters).join(", ");
-      throw new Error(`Unknown adapter "${name}". Available: ${available}`);
+      throw new Text2SqlUnknownAdapterError(name, this.adapterNames());
     }
     return adapter;
   }
+  #requireModel(op) {
+    const model = this.#config.model;
+    if (!model) {
+      throw new Error(`Text2Sql.${op}() requires a model in Text2SqlConfig`);
+    }
+    return model;
+  }
+  adapterNames() {
+    return Object.keys(this.#config.adapters);
+  }
+  hasAdapter(name) {
+    return name in this.#config.adapters;
+  }
+  async validate(name, sql) {
+    const adapter = this.#requireAdapter(name);
+    const result = this.#validateWith(adapter, sql);
+    return result;
+  }
+  async run(name, sql) {
+    const adapter = this.#requireAdapter(name);
+    const formatted = await this.#validateWith(adapter, sql);
+    const result = await adapter.execute(formatted);
+    if (!Array.isArray(result)) {
+      throw new Error("adapter.execute must return an array of rows");
+    }
+    const columns = result.length > 0 ? Object.keys(result[0]) : [];
+    return { rows: result, columns };
+  }
+  async #validateWith(adapter, sql) {
+    const formatted = adapter.format(sql);
+    const error = await adapter.validate(formatted);
+    if (error) throw new Text2SqlValidationError(error);
+    return formatted;
+  }
+  async index(options = {}) {
+    return this.#indexer.index({
+      adapterNames: options.names,
+      onProgress: options.onProgress
+    });
+  }
   async toSql(input, adapterName) {
     const adapter = this.#requireAdapter(adapterName);
+    const model = this.#requireModel("toSql");
     const fragments = await this.#indexer.indexAdapter(adapterName);
     const result = await toSql({
       input,
       adapter,
       fragments,
-      model: this.#config.model
+      model
     });
     return result.sql;
   }
@@ -5520,6 +5647,196 @@ var Text2Sql = class {
     return producer.toPairs();
   }
 };
+
+// packages/text2sql/src/lib/sql-command.ts
+var SQL_VALIDATE_REMINDER2 = 'Always run `sql validate <db> "..."` before `sql run <db> "..."` to catch syntax errors early.';
+var SqlCommandError = class extends Error {
+  exitCode;
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "SqlCommandError";
+    this.exitCode = exitCode;
+  }
+};
+function createSqlCommand(text2Sql, options = {}) {
+  const defaultOutputDir = options.outputDir ?? "/sql";
+  const subcommands = {
+    run: {
+      usage: 'run <db> "SELECT ..."',
+      description: "Execute query against <db> and store results",
+      repair: repairDbNameAndQuotedArg,
+      handler: (args, ctx) => handleRun(text2Sql, defaultOutputDir, args, ctx)
+    },
+    validate: {
+      usage: 'validate <db> "SELECT ..."',
+      description: "Validate query syntax against <db>",
+      repair: repairDbNameAndQuotedArg,
+      handler: (args) => handleValidate(text2Sql, args)
+    },
+    index: {
+      usage: "index [adapter ...]",
+      description: "Index adapter schemas and write context artifacts",
+      handler: (args, ctx) => handleIndex(text2Sql, defaultOutputDir, args, ctx)
+    }
+  };
+  return {
+    command: defineSubcommandGroup("sql", subcommands),
+    repair: buildSubcommandRepair2("sql", subcommands)
+  };
+}
+function parseFlags(args) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args,
+      options: {
+        "out-dir": { type: "string" },
+        all: { type: "boolean" }
+      },
+      allowPositionals: true,
+      strict: true
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new SqlCommandError(message, 1);
+  }
+  return {
+    positional: parsed.positionals,
+    outDir: parsed.values["out-dir"],
+    all: parsed.values.all === true
+  };
+}
+function resolveOutputDir(ctx, flags, fallback) {
+  const envOutDir = ctx.env.get("TEXT2SQL_OUT_DIR");
+  const candidate = flags.outDir ?? envOutDir ?? fallback;
+  return posix5.isAbsolute(candidate) ? candidate : posix5.resolve(ctx.cwd, candidate);
+}
+async function handleRun(text2Sql, defaultOutputDir, args, ctx) {
+  return runHandler("run", async () => {
+    const flags = parseFlags(args);
+    const meta = useBashMeta2();
+    meta?.setReminder(SQL_VALIDATE_REMINDER2);
+    const { name, sql } = takeDbAndSql(flags.positional, "run", text2Sql);
+    const outputDir = resolveOutputDir(ctx, flags, defaultOutputDir);
+    const { rows, columns } = await text2Sql.run(name, sql);
+    const outPath = posix5.join(outputDir, `${v7()}.json`);
+    await ctx.fs.mkdir(outputDir, { recursive: true });
+    await ctx.fs.writeFile(outPath, JSON.stringify(rows, null, 2));
+    return {
+      stdout: `results stored in ${outPath}
+columns: ${columns.join(", ") || "(none)"}
+rows: ${rows.length}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  });
+}
+async function handleValidate(text2Sql, args) {
+  return runHandler("validate", async () => {
+    const flags = parseFlags(args);
+    const { name, sql } = takeDbAndSql(flags.positional, "validate", text2Sql);
+    await text2Sql.validate(name, sql);
+    return { stdout: "valid\n", stderr: "", exitCode: 0 };
+  });
+}
+async function handleIndex(text2Sql, defaultOutputDir, args, ctx) {
+  return runHandler("index", async () => {
+    const flags = parseFlags(args);
+    const available = text2Sql.adapterNames();
+    const requested = flags.all ? [] : dedupe(flags.positional);
+    const names = requested.length === 0 ? available : requested;
+    for (const name of names) {
+      if (!text2Sql.hasAdapter(name)) {
+        throw new SqlCommandError(
+          `unknown adapter "${name}". Available: ${available.join(", ")}`,
+          1
+        );
+      }
+    }
+    const outputDir = resolveOutputDir(ctx, flags, defaultOutputDir);
+    const fragments = await text2Sql.index({ names });
+    const fragmentsPath = posix5.join(outputDir, `index-${v7()}.json`);
+    await ctx.fs.mkdir(outputDir, { recursive: true });
+    await ctx.fs.writeFile(fragmentsPath, JSON.stringify(fragments, null, 2));
+    const manifest = {
+      fragmentsPath,
+      eventsPath: null,
+      adapters: names,
+      fragments: countSchemaFragments(fragments)
+    };
+    return {
+      stdout: JSON.stringify(manifest, null, 2) + "\n",
+      stderr: "",
+      exitCode: 0
+    };
+  });
+}
+async function runHandler(name, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof SqlCommandError) {
+      return {
+        stdout: "",
+        stderr: `sql ${name}: ${error.message}
+`,
+        exitCode: error.exitCode
+      };
+    }
+    if (Text2SqlValidationError.isInstance(error) || Text2SqlUnknownAdapterError.isInstance(error)) {
+      return {
+        stdout: "",
+        stderr: `sql ${name}: ${error.message}
+`,
+        exitCode: 1
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { stdout: "", stderr: `sql ${name}: ${message}
+`, exitCode: 1 };
+  }
+}
+function takeDbAndSql(positional, cmd, text2Sql) {
+  const [db, ...rest] = positional;
+  const available = text2Sql.adapterNames().join(", ");
+  if (!db) {
+    throw new SqlCommandError(
+      `missing database name. Usage: sql ${cmd} <db> "SELECT ...". Available: ${available}`,
+      1
+    );
+  }
+  if (!text2Sql.hasAdapter(db)) {
+    throw new SqlCommandError(
+      `unknown database "${db}". Available: ${available}`,
+      1
+    );
+  }
+  const sql = rest.join(" ").trim();
+  if (!sql) {
+    throw new SqlCommandError("no query provided", 1);
+  }
+  return { name: db, sql };
+}
+function repairDbNameAndQuotedArg(rawArgs) {
+  const trimmed = rawArgs.trim();
+  if (!trimmed) return null;
+  const firstSpace = trimmed.search(/\s/);
+  if (firstSpace === -1) return null;
+  const dbName = trimmed.slice(0, firstSpace);
+  const rest = trimmed.slice(firstSpace + 1);
+  const repaired = repairQuotedArg2(rest);
+  if (repaired == null) return null;
+  return `${dbName} ${repaired}`;
+}
+function dedupe(values) {
+  return [...new Set(values)];
+}
+function countSchemaFragments(fragments) {
+  return fragments.reduce((count, adapterFragment) => {
+    return Array.isArray(adapterFragment.data) ? count + adapterFragment.data.length : count + 1;
+  }, 0);
+}
 export {
   Adapter,
   AdapterIndexer,
@@ -5536,10 +5853,13 @@ export {
   SqliteFs,
   TEXT2SQL_INDEX_PROGRESS_CHUNK,
   Text2Sql,
+  Text2SqlUnknownAdapterError,
+  Text2SqlValidationError,
   UnanswerableSQLError,
   applyTablesFilter,
   column,
   constraint,
+  createSqlCommand,
   createSqlCommandHooks,
   createSqlMetaHook,
   dialectInfo,