@deepagents/text2sql 7.0.2 → 7.1.0

package/README.md

@@ -440,8 +440,9 @@ const text2sql = new Text2Sql({
 });
 ```
 
-`FileIndexCache` writes atomically (temp + rename) and treats an unparseable
-file as a miss, so a torn read self-heals into a re-introspect. `FileIndexLock`
+`FileIndexCache` writes atomically (temp + rename) and treats a file that does
+not parse to context fragments as a miss, so a torn read self-heals into a
+re-introspect. `FileIndexLock`
 (built on `proper-lockfile`, options `{ dir?, namespace?, stale?, retries? }`)
 serializes processes that share a POSIX filesystem; a held lock auto-refreshes
 its mtime so a slow introspection is not mistaken for a crash, and acquisition

package/dist/bin/sql.js

@@ -3,6 +3,12 @@
 // packages/text2sql/src/bin/sql.ts
 import { cac } from "cac";
 
+// packages/text2sql/src/lib/index-cache.ts
+import {
+  isFragment,
+  isFragmentData
+} from "@deepagents/context";
+
 // packages/text2sql/src/lib/file-cache.ts
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -29,8 +35,14 @@ var FileCache = class {
   }
 };
 var JsonCache = class extends FileCache {
-  constructor(watermark, baseDir) {
+  #isValid;
+  /**
+   * @param isValid - Checks that a parsed cache file holds a T; a file that
+   * fails it is read as a miss.
+   */
+  constructor(watermark, isValid, baseDir) {
     super(watermark, ".json", baseDir);
+    this.#isValid = isValid;
   }
   async read() {
     const content = await this.get();
@@ -38,7 +50,8 @@ var JsonCache = class extends FileCache {
       return null;
     }
     try {
-      return JSON.parse(content);
+      const value = JSON.parse(content);
+      return this.#isValid(value) ? value : null;
     } catch {
       return null;
     }
@@ -64,9 +77,12 @@ var FileIndexCache = class {
   }
   #cacheFor(key) {
     const watermark = this.#namespace ? `${this.#namespace}-${key}` : key;
-    return new JsonCache(watermark, this.#dir);
+    return new JsonCache(watermark, isFragmentList, this.#dir);
   }
 };
+function isFragmentList(value) {
+  return Array.isArray(value) && value.every((item) => isFragment(item) && isFragmentData(item));
+}
 
 // packages/text2sql/src/lib/index-lock.ts
 import { createHash as createHash2 } from "node:crypto";
@@ -141,6 +157,7 @@ function validateAdapterNames(names) {
 
 // packages/text2sql/src/lib/adapters/adapter.ts
 import { format as formatSql } from "sql-formatter";
+import { z } from "zod";
 
 // packages/text2sql/src/lib/agents/exceptions.ts
 var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
@@ -413,7 +430,7 @@ import {
 } from "ai";
 import dedent from "dedent";
 import pRetry from "p-retry";
-import z from "zod";
+import z2 from "zod";
 import "@deepagents/agent";
 import {
   ContextEngine,
@@ -705,14 +722,14 @@ Question: ${options.input}
       const sqlOutput = structuredOutput({
         model,
         context,
-        schema: z.object({
-          result: z.union([
-            z.object({
-              sql: z.string().describe("The SQL query that answers the question"),
-              reasoning: z.string().describe("The reasoning steps taken to generate the SQL")
+        schema: z2.object({
+          result: z2.union([
+            z2.object({
+              sql: z2.string().describe("The SQL query that answers the question"),
+              reasoning: z2.string().describe("The reasoning steps taken to generate the SQL")
             }),
-            z.object({
-              error: z.string().describe(
+            z2.object({
+              error: z2.string().describe(
                 "Error message explaining why the question cannot be answered with the given schema"
               )
             })
@@ -763,11 +780,11 @@ Question: ${options.input}
         const forcedSqlOutput = structuredOutput({
           model,
           context,
-          schema: z.object({
-            sql: z.string().describe(
+          schema: z2.object({
+            sql: z2.string().describe(
               "Best-effort SQL query that answers the core intent using only available schema entities."
             ),
-            reasoning: z.string().describe("Reasoning steps for best-effort schema mapping.")
+            reasoning: z2.string().describe("Reasoning steps for best-effort schema mapping.")
           })
         });
         try {
@@ -969,8 +986,10 @@ var Text2Sql = class {
     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 };
+    const rows = result;
+    const [first] = rows;
+    const columns = typeof first === "object" && first !== null ? Object.keys(first) : [];
+    return { rows, columns };
   }
   async #validateWith(adapter, sql) {
     const formatted = adapter.format(sql);
@@ -1005,6 +1024,10 @@ var Text2Sql = class {
 
 // packages/text2sql/src/bin/command.ts
 import * as path3 from "node:path";
+import z3 from "zod";
+var cliWord = z3.union([z3.string(), z3.number()]).transform(String);
+var cliOptions = z3.record(z3.string(), z3.unknown());
+var queryArgs = z3.tuple([cliWord, z3.array(cliWord)]);
 var OUT_DIR_OPTION = {
   flag: "--out-dir <path>",
   description: "Output directory (default: $TEXT2SQL_OUT_DIR or ./sql)"
@@ -1047,9 +1070,9 @@ var SqlCommand = class {
 var SqlQueryCommand = class extends SqlCommand {
   args = "<db> <...sql>";
   async execute(ctx, args, options) {
-    const [db, sqlParts] = args;
+    const [db, sqlParts] = queryArgs.parse(args);
     const name = this.resolveAdapterName(ctx.text2Sql, db);
-    const sql = (sqlParts ?? []).join(" ").trim();
+    const sql = sqlParts.join(" ").trim();
     if (!sql) this.fail("no query provided");
     try {
       return await this.runQuery(ctx, name, sql, options);
@@ -1072,6 +1095,7 @@ import {
 import * as path4 from "node:path";
 import { finished } from "node:stream/promises";
 import { v7 } from "uuid";
+import z4 from "zod";
 
 // packages/text2sql/src/bin/commands/indexing-formatter.ts
 var REDUNDANT_MESSAGE_TYPES = /* @__PURE__ */ new Set([
@@ -1092,6 +1116,7 @@ function formatPretty(event) {
 }
 
 // packages/text2sql/src/bin/commands/index.ts
+var indexArgs = z4.tuple([z4.array(cliWord)]);
 var IndexCommand = class extends SqlCommand {
   name = "index";
   description = "Index adapter schemas and write context artifacts";
@@ -1107,7 +1132,7 @@ var IndexCommand = class extends SqlCommand {
     OUT_DIR_OPTION
   ];
   async execute(ctx, args, options) {
-    const adapterNames = args[0] ?? [];
+    const [adapterNames] = indexArgs.parse(args);
     const requested = options.all ? [] : adapterNames;
     const names = this.resolveNames(ctx.text2Sql, requested);
     const verbose = this.resolveVerbose(options.verbose);
@@ -1203,14 +1228,14 @@ async function probeFifoWriter(eventsPath, stderr) {
   try {
     stats = await stat(eventsPath);
   } catch (err) {
-    if (err.code === "ENOENT") return null;
+    if (hasErrorCode(err, "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") {
+    if (hasErrorCode(err, "ENXIO")) {
       stderr.write(`sql index: waiting for reader on FIFO ${eventsPath}...
 `);
       return null;
@@ -1218,6 +1243,9 @@ async function probeFifoWriter(eventsPath, stderr) {
     throw err;
   }
 }
+function hasErrorCode(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
 function waitForOpen(stream) {
   return new Promise((resolve4, reject) => {
     if (!stream.pending) {
@@ -1301,15 +1329,12 @@ async function loadAdapters() {
     );
   }
   const specifier = target.startsWith(".") || target.startsWith("/") ? pathToFileURL(resolve3(target)).href : target;
-  let mod;
-  try {
-    mod = await import(specifier);
-  } catch (cause) {
+  const mod = await import(specifier).catch((cause) => {
     throw new Error(
       `TEXT2SQL_ADAPTERS=${target}: failed to import module - ${errorMessage2(cause)}`
     );
-  }
-  const exported = mod.default;
+  });
+  const exported = typeof mod === "object" && mod !== null && "default" in mod ? mod.default : void 0;
   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)}).`
@@ -1321,24 +1346,24 @@ async function loadAdapters() {
       `TEXT2SQL_ADAPTERS=${target}: default export is an empty object - declare at least one adapter.`
     );
   }
+  const adapters = {};
   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).`
       );
     }
+    adapters[name] = value;
   }
   try {
     validateAdapterNames(entries.map(([name]) => name));
   } catch (cause) {
     throw new Error(`TEXT2SQL_ADAPTERS=${target}: ${errorMessage2(cause)}`);
   }
-  return exported;
+  return adapters;
 }
 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";
+  return typeof value === "object" && value !== null && "format" in value && typeof value.format === "function" && "validate" in value && typeof value.validate === "function" && "execute" in value && typeof value.execute === "function";
 }
 function describe(value) {
   if (value === null) return "null";
@@ -1387,7 +1412,7 @@ function registerCommand(cli2, command) {
     cliCommand.option(option.flag, option.description);
   }
   cliCommand.action(async (...callArgs) => {
-    const options = callArgs[callArgs.length - 1] ?? {};
+    const options = cliOptions.parse(callArgs.at(-1));
     const positional = callArgs.slice(0, -1);
     return runCommand(command, positional, options);
   });