@deepagents/text2sql 0.39.0 → 2.1.0

package/dist/bin/sql.js

@@ -0,0 +1,795 @@
+#!/usr/bin/env node
+
+// packages/text2sql/src/bin/sql.ts
+import { cac } from "cac";
+
+// packages/text2sql/src/bin/command.ts
+import * as path from "node:path";
+var OUT_DIR_OPTION = {
+  flag: "--out-dir <path>",
+  description: "Output directory (default: $TEXT2SQL_OUT_DIR or ./sql)"
+};
+function resolveOutputDir(ctx, options) {
+  const explicit = typeof options.outDir === "string" ? options.outDir : void 0;
+  return path.resolve(ctx.cwd, explicit ?? ctx.env.TEXT2SQL_OUT_DIR ?? "./sql");
+}
+var CommandError = class extends Error {
+  command;
+  exitCode;
+  constructor(command, message, exitCode = 1) {
+    super(message);
+    this.name = "CommandError";
+    this.command = command;
+    this.exitCode = exitCode;
+  }
+};
+function renderCommandError(error, stderr) {
+  stderr.write(`sql ${error.command}: ${error.message}
+`);
+}
+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 { constants, createWriteStream } from "node:fs";
+import {
+  mkdir,
+  open,
+  stat,
+  writeFile as writeFile2
+} from "node:fs/promises";
+import * as path3 from "node:path";
+import { finished } from "node:stream/promises";
+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 path2 from "node:path";
+var FileCache = class {
+  path;
+  constructor(watermark, extension = ".txt") {
+    const hash = createHash("md5").update(watermark).digest("hex");
+    this.path = path2.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 `index-${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/indexing-formatter.ts
+var REDUNDANT_MESSAGE_TYPES = /* @__PURE__ */ new Set([
+  "adapter:start",
+  "adapter:end"
+]);
+function formatPretty(event) {
+  const head = event.adapter ? `${event.type} ${event.adapter}` : event.type;
+  const parts = [`[${head}]`];
+  if (event.phase) parts.push(`phase=${event.phase}`);
+  if (event.table) parts.push(`table=${event.table}`);
+  if (typeof event.current === "number" && typeof event.total === "number" && !event.type.endsWith(":start")) {
+    parts.push(`${event.current}/${event.total}`);
+  }
+  if (event.cached) parts.push("cached");
+  if (!REDUNDANT_MESSAGE_TYPES.has(event.type)) parts.push(event.message);
+  return parts.join(" ");
+}
+
+// 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] [--verbose [pretty|json]] [adapter ...]";
+  helpDisplay = "[--all] [--verbose] [adapter ...]";
+  options = [
+    { flag: "--all", description: "Index all adapters (default)" },
+    {
+      flag: "-v, --verbose [format]",
+      description: "Mirror progress events to stderr (format: pretty (default) | json)"
+    },
+    OUT_DIR_OPTION
+  ];
+  async execute(ctx, args, options) {
+    const adapterNames = args[0] ?? [];
+    const requested = options.all ? [] : adapterNames;
+    const names = this.resolveNames(ctx.adapters, requested);
+    const verbose = this.resolveVerbose(options.verbose);
+    const outputDir = resolveOutputDir(ctx, options);
+    const id = v7();
+    const fragmentsPath = path3.join(outputDir, `index-${id}.json`);
+    const explicitEventsPath = resolveExplicitEventsPath(ctx);
+    const eventsPath = explicitEventsPath ?? path3.join(outputDir, `index-${id}.events.ndjson`);
+    try {
+      await mkdir(outputDir, { recursive: true });
+      if (explicitEventsPath) {
+        await mkdir(path3.dirname(explicitEventsPath), { recursive: true });
+      }
+      const eventsStream = await openEventsWriter(
+        eventsPath,
+        explicitEventsPath,
+        ctx.stderr
+      );
+      try {
+        const indexer = new AdapterIndexer({
+          adapters: ctx.adapters,
+          version: ctx.env.TEXT2SQL_INDEX_VERSION
+        });
+        const fragments = await indexer.index({
+          adapterNames: names,
+          onProgress: createProgressHandler(eventsStream, verbose, ctx.stderr)
+        });
+        await writeFile2(fragmentsPath, JSON.stringify(fragments, null, 2));
+        const manifest = {
+          fragmentsPath,
+          eventsPath,
+          adapters: names,
+          fragments: countSchemaFragments(fragments)
+        };
+        ctx.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+        return 0;
+      } finally {
+        eventsStream.end();
+        await finished(eventsStream).catch(() => {
+        });
+      }
+    } 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;
+  }
+  resolveVerbose(value) {
+    if (value === void 0 || value === false) return null;
+    if (value === true || value === "" || value === "pretty") return "pretty";
+    if (value === "json") return "json";
+    this.fail(
+      `invalid --verbose value "${String(value)}". Expected "pretty" or "json".`
+    );
+  }
+};
+function createProgressHandler(eventsStream, verbose, stderr) {
+  return (event) => {
+    const stamped = { ...event, timestampMs: event.timestampMs ?? Date.now() };
+    const json = JSON.stringify(stamped) + "\n";
+    eventsStream.write(json);
+    if (verbose === "pretty") stderr.write(formatPretty(stamped) + "\n");
+    else if (verbose === "json") stderr.write(json);
+  };
+}
+function resolveExplicitEventsPath(ctx) {
+  const explicit = ctx.env.TEXT2SQL_INDEX_EVENTS_PATH?.trim();
+  return explicit ? path3.resolve(ctx.cwd, explicit) : null;
+}
+async function openEventsWriter(eventsPath, explicitEventsPath, stderr) {
+  const probe = explicitEventsPath ? await probeFifoWriter(explicitEventsPath, stderr) : null;
+  const stream = createWriteStream(eventsPath, {
+    flags: "a",
+    encoding: "utf-8"
+  });
+  try {
+    await waitForOpen(stream);
+    return stream;
+  } catch (err) {
+    stream.destroy();
+    throw err;
+  } finally {
+    await probe?.close().catch(() => {
+    });
+  }
+}
+async function probeFifoWriter(eventsPath, stderr) {
+  let stats;
+  try {
+    stats = await stat(eventsPath);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  if (!stats.isFIFO()) return null;
+  try {
+    return await open(eventsPath, constants.O_WRONLY | constants.O_NONBLOCK);
+  } catch (err) {
+    if (err.code === "ENXIO") {
+      stderr.write(`sql index: waiting for reader on FIFO ${eventsPath}...
+`);
+      return null;
+    }
+    throw err;
+  }
+}
+function waitForOpen(stream) {
+  return new Promise((resolve4, reject) => {
+    if (!stream.pending) {
+      resolve4();
+      return;
+    }
+    const onOpen = () => {
+      stream.off("error", onError);
+      resolve4();
+    };
+    const onError = (err) => {
+      stream.off("open", onOpen);
+      reject(err);
+    };
+    stream.once("open", onOpen);
+    stream.once("error", onError);
+  });
+}
+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 path4 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 = [OUT_DIR_OPTION];
+  async afterValidation(ctx, adapter, sql, options) {
+    const outputDir = 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 = path4.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]) : [];
+    ctx.stdout.write(`results stored in ${outPath}
+`);
+    ctx.stdout.write(`columns: ${columns.join(", ") || "(none)"}
+`);
+    ctx.stdout.write(`rows: ${rows.length}
+`);
+    return 0;
+  }
+};
+
+// 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(ctx) {
+    ctx.stdout.write("valid\n");
+    return 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.exitCode = 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,
+      stdout: process.stdout,
+      stderr: process.stderr
+    };
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}
+`);
+    return 2;
+  }
+  try {
+    return await command.execute(ctx, positional, options);
+  } catch (error) {
+    if (error instanceof CommandError) {
+      renderCommandError(error, process.stderr);
+      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 writeCliError(error) {
+  if (error instanceof Error && error.name === "CACError") {
+    process.stderr.write(`sql: ${error.message}
+`);
+    cli.outputHelp();
+    return 2;
+  }
+  if (error instanceof CommandError) {
+    renderCommandError(error, process.stderr);
+    return error.exitCode;
+  }
+  process.stderr.write(
+    `sql: unexpected error: ${error instanceof Error ? error.stack ?? error.message : String(error)}
+`
+  );
+  return 1;
+}