@deepagents/text2sql 0.38.1 → 1.0.0

package/dist/bin/sql.js

@@ -0,0 +1,699 @@
+#!/usr/bin/env node
+
+// packages/text2sql/src/bin/sql.ts
+import { cac } from "cac";
+
+// packages/text2sql/src/bin/command.ts
+var CommandError = class extends Error {
+  command;
+  exitCode;
+  constructor(command, message, exitCode = 1) {
+    super(message);
+    this.name = "CommandError";
+    this.command = command;
+    this.exitCode = exitCode;
+  }
+  toResult() {
+    return {
+      stdout: "",
+      stderr: `sql ${this.command}: ${this.message}
+`,
+      exitCode: this.exitCode
+    };
+  }
+};
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var SqlCommand = class {
+  options = [];
+  helpDisplay;
+  fail(message, exitCode = 1) {
+    throw new CommandError(this.name, message, exitCode);
+  }
+  requireAdapter(adapters, db) {
+    const available = Object.keys(adapters).join(", ") || "(none configured)";
+    if (!db) {
+      this.fail(
+        `missing database name. Usage: sql ${this.name} ${this.usage}. Available: ${available}`
+      );
+    }
+    const adapter = adapters[db];
+    if (!adapter) {
+      this.fail(`unknown database "${db}". Available: ${available}`);
+    }
+    return adapter;
+  }
+};
+var SqlQueryCommand = class extends SqlCommand {
+  args = "<db> <...sql>";
+  async execute(ctx, args, options) {
+    const [db, sqlParts] = args;
+    const adapter = this.requireAdapter(ctx.adapters, db);
+    const sql = (sqlParts ?? []).join(" ").trim();
+    if (!sql) this.fail("no query provided");
+    const formatted = await this.formatAndValidate(adapter, sql);
+    return this.afterValidation(ctx, adapter, formatted, options);
+  }
+  async formatAndValidate(adapter, sql) {
+    let formatted;
+    try {
+      formatted = adapter.format(sql);
+    } catch (error) {
+      this.fail(errorMessage(error));
+    }
+    try {
+      const syntaxError = await adapter.validate(formatted);
+      if (syntaxError) this.fail(syntaxError);
+    } catch (error) {
+      this.fail(errorMessage(error));
+    }
+    return formatted;
+  }
+};
+
+// packages/text2sql/src/bin/commands/index.ts
+import { appendFileSync } from "node:fs";
+import { mkdir, writeFile as writeFile2 } from "node:fs/promises";
+import * as path2 from "node:path";
+import { v7 } from "uuid";
+
+// packages/text2sql/src/lib/adapter-index.ts
+import { fragment } from "@deepagents/context";
+
+// packages/text2sql/src/lib/adapter-name.ts
+var ADAPTER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isValidAdapterName(name) {
+  return name != null && ADAPTER_NAME_PATTERN.test(name);
+}
+function validateAdapterNames(names) {
+  for (const name of names) {
+    if (!isValidAdapterName(name)) {
+      throw new Error(
+        `Invalid adapter name "${name}": must match ${ADAPTER_NAME_PATTERN}`
+      );
+    }
+  }
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+import { format as formatSql } from "sql-formatter";
+
+// packages/text2sql/src/lib/agents/exceptions.ts
+var sqlValidationMarker = Symbol("SQLValidationError");
+var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
+var sqlScopeMarker = Symbol("SQLScopeError");
+var sqlReadOnlyMarker = Symbol("SQLReadOnlyError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
+var SQLReadOnlyError = class _SQLReadOnlyError extends Error {
+  [sqlReadOnlyMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLReadOnlyError";
+    this[sqlReadOnlyMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLReadOnlyError && error[sqlReadOnlyMarker] === true;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
+function createGroundingContext(options = {}) {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0,
+    cache: /* @__PURE__ */ new Map(),
+    onProgress: timestampProgress(options.onProgress)
+  };
+}
+
+// packages/text2sql/src/lib/adapters/runtime-scope.ts
+import nodeSqlParser from "node-sql-parser";
+var { Parser } = nodeSqlParser;
+var parser = new Parser();
+
+// packages/text2sql/src/lib/file-cache.ts
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+var FileCache = class {
+  path;
+  constructor(watermark, extension = ".txt") {
+    const hash = createHash("md5").update(watermark).digest("hex");
+    this.path = path.join(tmpdir(), `text2sql-${hash}${extension}`);
+  }
+  async get() {
+    if (existsSync(this.path)) {
+      return readFile(this.path, "utf-8");
+    }
+    return null;
+  }
+  set(content) {
+    return writeFile(this.path, content, "utf-8");
+  }
+};
+var JsonCache = class extends FileCache {
+  constructor(watermark) {
+    super(watermark, ".json");
+  }
+  async read() {
+    const content = await this.get();
+    if (content) {
+      return JSON.parse(content);
+    }
+    return null;
+  }
+  write(data) {
+    return this.set(JSON.stringify(data));
+  }
+};
+
+// packages/text2sql/src/lib/adapter-index.ts
+var noopProgressHandler = () => {
+};
+function timestampProgressHandler(onProgress) {
+  if (!onProgress) return noopProgressHandler;
+  return (event) => {
+    onProgress({
+      ...event,
+      timestampMs: event.timestampMs ?? Date.now()
+    });
+  };
+}
+var AdapterIndexer = class {
+  #adapters;
+  #version;
+  #cacheKey;
+  constructor(options) {
+    const adapterNames = Object.keys(options.adapters);
+    if (adapterNames.length === 0) {
+      throw new Error("AdapterIndexer requires at least one adapter");
+    }
+    validateAdapterNames(adapterNames);
+    this.#adapters = options.adapters;
+    this.#version = options.version;
+    this.#cacheKey = options.cacheKey;
+  }
+  async index(options = {}) {
+    const progress = timestampProgressHandler(options.onProgress);
+    const entries = this.#resolveIndexEntries(options.adapterNames);
+    progress({
+      type: "index:start",
+      message: `Indexing ${entries.length} adapter${entries.length === 1 ? "" : "s"}...`,
+      current: 0,
+      total: entries.length
+    });
+    const settled = await Promise.allSettled(
+      entries.map(async ([name, adapter]) => {
+        const schema = await this.#indexAdapter(name, adapter, progress);
+        return fragment(name, ...schema);
+      })
+    );
+    const failed = settled.find((result) => result.status === "rejected");
+    if (failed) {
+      progress({
+        type: "index:error",
+        message: failed.reason instanceof Error ? failed.reason.message : String(failed.reason)
+      });
+      throw failed.reason;
+    }
+    const wrapped = settled.map((result) => {
+      if (result.status === "rejected") {
+        throw result.reason;
+      }
+      return result.value;
+    });
+    progress({
+      type: "index:end",
+      message: "Finished indexing adapters.",
+      current: entries.length,
+      total: entries.length
+    });
+    return wrapped;
+  }
+  async indexAdapter(name, options = {}) {
+    const adapter = this.#adapters[name];
+    if (!adapter) {
+      const available = Object.keys(this.#adapters).join(", ");
+      throw new Error(`unknown adapter "${name}". Available: ${available}`);
+    }
+    return this.#indexAdapter(
+      name,
+      adapter,
+      timestampProgressHandler(options.onProgress)
+    );
+  }
+  async #indexAdapter(name, adapter, progress) {
+    progress({
+      type: "adapter:start",
+      adapter: name,
+      message: `Indexing adapter "${name}"...`
+    });
+    const cacheKey = this.#adapterCacheKey(name);
+    const cache = cacheKey ? new JsonCache(cacheKey) : void 0;
+    try {
+      const cached = await cache?.read();
+      if (cached) {
+        progress({
+          type: "adapter:cache-hit",
+          adapter: name,
+          message: `Using cached index for adapter "${name}".`,
+          cached: true
+        });
+        progress({
+          type: "adapter:end",
+          adapter: name,
+          message: `Finished indexing adapter "${name}".`,
+          cached: true
+        });
+        return cached;
+      }
+      if (cache) {
+        progress({
+          type: "adapter:cache-miss",
+          adapter: name,
+          message: `No cached index for adapter "${name}".`,
+          cached: false
+        });
+      }
+      const ctx = createGroundingContext({
+        onProgress: (event) => progress(adapterProgressEvent(name, event))
+      });
+      const fragments = await adapter.introspect(ctx);
+      await cache?.write(fragments);
+      progress({
+        type: "adapter:end",
+        adapter: name,
+        message: `Finished indexing adapter "${name}".`,
+        cached: false
+      });
+      return fragments;
+    } catch (error) {
+      const reason = errorMessage2(error);
+      progress({
+        type: "adapter:error",
+        adapter: name,
+        message: `Failed indexing adapter "${name}": ${reason}`
+      });
+      throw new Error(`introspecting adapter "${name}": ${reason}`, {
+        cause: error
+      });
+    }
+  }
+  #resolveIndexEntries(adapterNames) {
+    const availableNames = Object.keys(this.#adapters);
+    const requestedNames = adapterNames && adapterNames.length > 0 ? [...new Set(adapterNames)] : availableNames;
+    const available = availableNames.join(", ");
+    return requestedNames.map((name) => {
+      const adapter = this.#adapters[name];
+      if (!adapter) {
+        throw new Error(`unknown adapter "${name}". Available: ${available}`);
+      }
+      return [name, adapter];
+    });
+  }
+  #adapterCacheKey(name) {
+    const configured = this.#cacheKey?.(name);
+    if (configured !== void 0) {
+      return configured;
+    }
+    if (this.#version) {
+      return `introspection-${this.#version}-${name}`;
+    }
+    return void 0;
+  }
+};
+function adapterProgressEvent(adapter, progress) {
+  return {
+    type: progress.type,
+    adapter,
+    phase: progress.phase,
+    table: progress.table,
+    message: progress.message,
+    current: progress.current,
+    total: progress.total,
+    cached: false,
+    timestampMs: progress.timestampMs
+  };
+}
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// packages/text2sql/src/bin/commands/index.ts
+var IndexCommand = class extends SqlCommand {
+  name = "index";
+  description = "Index adapter schemas and write context artifacts";
+  args = "[...adapters]";
+  usage = "[--all] [adapter ...]";
+  helpDisplay = "[--all] [adapter ...]";
+  options = [
+    { flag: "--all", description: "Index all adapters (default)" }
+  ];
+  async execute(ctx, args, options) {
+    const adapterNames = args[0] ?? [];
+    const requested = options.all ? [] : adapterNames;
+    const names = this.resolveNames(ctx.adapters, requested);
+    const outputDir = path2.resolve(ctx.cwd, "./sql");
+    const id = v7();
+    const fragmentsPath = path2.join(outputDir, `index-${id}.json`);
+    const eventsPath = path2.join(outputDir, `index-${id}.events.ndjson`);
+    try {
+      await mkdir(outputDir, { recursive: true });
+      await writeFile2(eventsPath, "");
+      const indexer = new AdapterIndexer({ adapters: ctx.adapters });
+      const fragments = await indexer.index({
+        adapterNames: names,
+        onProgress: (event) => appendProgressEvent(eventsPath, event)
+      });
+      await writeFile2(fragmentsPath, JSON.stringify(fragments, null, 2));
+      const manifest = {
+        fragmentsPath,
+        eventsPath,
+        adapters: names,
+        fragments: countSchemaFragments(fragments)
+      };
+      return {
+        stdout: JSON.stringify(manifest, null, 2) + "\n",
+        stderr: "",
+        exitCode: 0
+      };
+    } catch (error) {
+      this.fail(errorMessage(error));
+    }
+  }
+  resolveNames(adapters, requested) {
+    const availableNames = Object.keys(adapters);
+    const available = availableNames.join(", ") || "(none configured)";
+    const names = requested.length === 0 ? availableNames : dedupe(requested);
+    for (const name of names) {
+      if (!adapters[name]) {
+        this.fail(`unknown adapter "${name}". Available: ${available}`);
+      }
+    }
+    return names;
+  }
+};
+function appendProgressEvent(eventsPath, event) {
+  appendFileSync(
+    eventsPath,
+    JSON.stringify({
+      ...event,
+      timestampMs: event.timestampMs ?? Date.now()
+    }) + "\n"
+  );
+}
+function countSchemaFragments(fragments) {
+  return fragments.reduce((count, adapterFragment) => {
+    if (Array.isArray(adapterFragment.data)) {
+      return count + adapterFragment.data.length;
+    }
+    return count + 1;
+  }, 0);
+}
+function dedupe(values) {
+  return [...new Set(values)];
+}
+
+// packages/text2sql/src/bin/commands/run.ts
+import { mkdir as mkdir2, writeFile as writeFile3 } from "node:fs/promises";
+import * as path3 from "node:path";
+import { v7 as v72 } from "uuid";
+var RunCommand = class extends SqlQueryCommand {
+  name = "run";
+  description = "Execute query against <db> and store results";
+  usage = '<db> "SELECT ..." [--out-dir <path>]';
+  helpDisplay = '<db> "SELECT ..."';
+  options = [
+    {
+      flag: "--out-dir <path>",
+      description: "Directory for `sql run` result files (default: $TEXT2SQL_OUT_DIR or ./sql)"
+    }
+  ];
+  async afterValidation(ctx, adapter, sql, options) {
+    const outputDir = this.resolveOutputDir(ctx, options);
+    let rows;
+    try {
+      rows = await adapter.execute(sql);
+    } catch (error) {
+      this.fail(errorMessage(error));
+    }
+    if (!Array.isArray(rows)) {
+      this.fail("adapter.execute must return an array of rows");
+    }
+    const outPath = path3.join(outputDir, `${v72()}.json`);
+    try {
+      await mkdir2(outputDir, { recursive: true });
+      await writeFile3(outPath, JSON.stringify(rows, null, 2));
+    } catch (error) {
+      this.fail(errorMessage(error));
+    }
+    const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+    return {
+      stdout: [
+        `results stored in ${outPath}`,
+        `columns: ${columns.join(", ") || "(none)"}`,
+        `rows: ${rows.length}`
+      ].join("\n") + "\n",
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  resolveOutputDir(ctx, options) {
+    const explicit = typeof options.outDir === "string" ? options.outDir : void 0;
+    return path3.resolve(
+      ctx.cwd,
+      explicit ?? ctx.env.TEXT2SQL_OUT_DIR ?? "./sql"
+    );
+  }
+};
+
+// packages/text2sql/src/bin/commands/validate.ts
+var ValidateCommand = class extends SqlQueryCommand {
+  name = "validate";
+  description = "Validate query syntax against <db>";
+  usage = '<db> "SELECT ..."';
+  helpDisplay = '<db> "SELECT ..."';
+  async afterValidation() {
+    return { stdout: "valid\n", stderr: "", exitCode: 0 };
+  }
+};
+
+// packages/text2sql/src/bin/commands/registry.ts
+var commands = [
+  new RunCommand(),
+  new ValidateCommand(),
+  new IndexCommand()
+];
+
+// packages/text2sql/src/bin/load-adapters.ts
+import { resolve as resolve3 } from "node:path";
+import { pathToFileURL } from "node:url";
+async function loadAdapters() {
+  const target = process.env.TEXT2SQL_ADAPTERS;
+  if (!target) {
+    throw new Error(
+      "TEXT2SQL_ADAPTERS env var is not set. Point it at a module whose default export is Record<string, Adapter>."
+    );
+  }
+  const specifier = target.startsWith(".") || target.startsWith("/") ? pathToFileURL(resolve3(target)).href : target;
+  let mod;
+  try {
+    mod = await import(specifier);
+  } catch (cause) {
+    throw new Error(
+      `TEXT2SQL_ADAPTERS=${target}: failed to import module - ${errorMessage(cause)}`
+    );
+  }
+  const exported = mod.default;
+  if (!exported || typeof exported !== "object" || Array.isArray(exported)) {
+    throw new Error(
+      `TEXT2SQL_ADAPTERS=${target}: default export must be a Record<string, Adapter> (got ${describe(exported)}).`
+    );
+  }
+  const entries = Object.entries(exported);
+  if (entries.length === 0) {
+    throw new Error(
+      `TEXT2SQL_ADAPTERS=${target}: default export is an empty object - declare at least one adapter.`
+    );
+  }
+  for (const [name, value] of entries) {
+    if (!isAdapterShape(value)) {
+      throw new Error(
+        `TEXT2SQL_ADAPTERS=${target}: adapter "${name}" is missing one of the required methods (format, validate, execute).`
+      );
+    }
+  }
+  try {
+    validateAdapterNames(entries.map(([name]) => name));
+  } catch (cause) {
+    throw new Error(`TEXT2SQL_ADAPTERS=${target}: ${errorMessage(cause)}`);
+  }
+  return exported;
+}
+function isAdapterShape(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.format === "function" && typeof v.validate === "function" && typeof v.execute === "function";
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+// packages/text2sql/src/bin/sql.ts
+var cli = cac("sql");
+cli.usage("<run|validate|index> ...").help(
+  (sections) => sections.map(
+    (section) => section.title === "Commands" ? { ...section, body: rewriteCommandsHelp(section.body) } : section
+  )
+);
+for (const command of commands) {
+  registerCommand(cli, command);
+}
+process.exit(await runCli());
+async function runCli() {
+  try {
+    cli.parse(process.argv, { run: false });
+    if (cli.options.help) return 0;
+    if (!cli.matchedCommand) {
+      try {
+        cli.globalCommand.checkUnknownOptions();
+        cli.globalCommand.checkOptionValue();
+      } catch (error) {
+        return writeCliError(error);
+      }
+      const [subcommand] = cli.args;
+      const label = subcommand ? `unknown subcommand "${String(subcommand)}"` : "missing subcommand";
+      process.stderr.write(`sql: ${label}
+`);
+      cli.outputHelp();
+      return 2;
+    }
+    const result = await cli.runMatchedCommand();
+    return typeof result === "number" ? result : 0;
+  } catch (error) {
+    return writeCliError(error);
+  }
+}
+function registerCommand(cli2, command) {
+  const cliCommand = cli2.command(`${command.name} ${command.args}`, command.description).usage(command.usage);
+  for (const option of command.options) {
+    cliCommand.option(option.flag, option.description);
+  }
+  cliCommand.action(async (...callArgs) => {
+    const options = callArgs[callArgs.length - 1] ?? {};
+    const positional = callArgs.slice(0, -1);
+    return runCommand(command, positional, options);
+  });
+}
+async function runCommand(command, positional, options) {
+  let ctx;
+  try {
+    ctx = {
+      adapters: await loadAdapters(),
+      cwd: process.cwd(),
+      env: process.env
+    };
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}
+`);
+    return 2;
+  }
+  try {
+    const result = await command.execute(ctx, positional, options);
+    writeCommandResult(result);
+    return result.exitCode;
+  } catch (error) {
+    if (error instanceof CommandError) {
+      writeCommandResult(error.toResult());
+      return error.exitCode;
+    }
+    throw error;
+  }
+}
+function rewriteCommandsHelp(body) {
+  return commands.reduce((current, command) => {
+    if (!command.helpDisplay) return current;
+    return current.replace(
+      `${command.name} ${command.args}`,
+      `${command.name} ${command.helpDisplay}`
+    );
+  }, body);
+}
+function writeCommandResult(result) {
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) {
+    const out = result.stderr.endsWith("\n") ? result.stderr : result.stderr + "\n";
+    process.stderr.write(out);
+  }
+}
+function writeCliError(error) {
+  if (error instanceof Error && error.name === "CACError") {
+    process.stderr.write(`sql: ${error.message}
+`);
+    cli.outputHelp();
+    return 2;
+  }
+  if (error instanceof CommandError) {
+    writeCommandResult(error.toResult());
+    return error.exitCode;
+  }
+  process.stderr.write(
+    `sql: unexpected error: ${error instanceof Error ? error.stack ?? error.message : String(error)}
+`
+  );
+  return 1;
+}

package/dist/index.d.ts

@@ -1,15 +1,14 @@
 export { isValidAdapterName, validateAdapterNames, } from './lib/adapter-name.ts';
 export * from './lib/adapters/adapter.ts';
 export * from './lib/agents/exceptions.ts';
-export * from './lib/agents/sql-command.ts';
-export * from './lib/agents/sql-transform-plugins.ts';
 export * from './lib/agents/sql.agent.ts';
 export * from './lib/agents/suggestions.agents.ts';
+export * from './lib/adapter-index.ts';
 export * from './lib/checkpoint.ts';
 export * from './lib/file-cache.ts';
 export * from './lib/fragments/schema.ts';
 export * from './lib/fs/index.ts';
 export * from './lib/instructions.ts';
-export * from './lib/sandbox.ts';
+export * from './lib/sql-hooks.ts';
 export * from './lib/sql.ts';
 //# sourceMappingURL=index.d.ts.map