@deepagents/text2sql 0.29.1 → 0.31.0

package/dist/index.js

@@ -1,6 +1,48 @@
 // 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 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;
+  }
+};
+
 // packages/text2sql/src/lib/fragments/schema.ts
 function dialectInfo(input) {
   return {
@@ -104,6 +146,134 @@ function createGroundingContext() {
   };
 }
 
+// packages/text2sql/src/lib/adapters/runtime-scope.ts
+import nodeSqlParser from "node-sql-parser";
+var { Parser } = nodeSqlParser;
+var parser = new Parser();
+function extractBaseEntityReferences(sql, dialect) {
+  const ast = parser.astify(sql, { database: dialect });
+  const state = {
+    cteNames: /* @__PURE__ */ new Set(),
+    references: /* @__PURE__ */ new Map()
+  };
+  visitNode(ast, state);
+  return Array.from(state.references.values());
+}
+function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
+  return {
+    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
+    error_type: "OUT_OF_SCOPE",
+    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
+    sql_attempted: sql,
+    referenced_entities: referencedEntities,
+    allowed_entities: allowedEntities
+  };
+}
+function buildScopeParseErrorPayload(sql, dialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: dialect,
+    parser_error: parserError
+  };
+}
+function visitNode(node, state) {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      visitNode(item, state);
+    }
+    return;
+  }
+  if (!isAstLike(node)) {
+    return;
+  }
+  if (isStatementNode(node)) {
+    visitStatement(node, state);
+    return;
+  }
+  if (isTableReferenceNode(node)) {
+    addReference(node, state);
+  }
+  for (const value of Object.values(node)) {
+    visitNode(value, state);
+  }
+}
+function visitStatement(node, parentState) {
+  const localState = {
+    cteNames: new Set(parentState.cteNames),
+    references: parentState.references
+  };
+  const withItems = Array.isArray(node.with) ? node.with : [];
+  for (const item of withItems) {
+    if (!isAstLike(item)) {
+      continue;
+    }
+    const cteName = readCteName(item);
+    if (cteName) {
+      localState.cteNames.add(caseFold(cteName));
+    }
+  }
+  for (const item of withItems) {
+    if (!isAstLike(item)) {
+      continue;
+    }
+    visitNode(item.stmt, localState);
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "with") {
+      continue;
+    }
+    visitNode(value, localState);
+  }
+}
+function addReference(node, state) {
+  const table2 = typeof node.table === "string" ? node.table : null;
+  if (!table2) {
+    return;
+  }
+  if (state.cteNames.has(caseFold(table2))) {
+    return;
+  }
+  const db = typeof node.db === "string" ? node.db : null;
+  const key = db ? `${db}.${table2}` : table2;
+  if (!state.references.has(key)) {
+    state.references.set(key, { db, table: table2 });
+  }
+}
+function readCteName(node) {
+  const name = node.name;
+  if (typeof name === "string") {
+    return name;
+  }
+  if (!isAstLike(name)) {
+    return void 0;
+  }
+  const value = name.value;
+  return typeof value === "string" ? value : void 0;
+}
+function isStatementNode(node) {
+  const type = node.type;
+  return typeof type === "string" && ["delete", "insert", "replace", "select", "update"].includes(type);
+}
+function isTableReferenceNode(node) {
+  if (node.type === "column_ref") {
+    return false;
+  }
+  if (typeof node.table !== "string") {
+    return false;
+  }
+  return "addition" in node || "as" in node || "db" in node || "join" in node || "operator" in node || "surround" in node || "table_hint" in node || "temporal_table" in node;
+}
+function isAstLike(value) {
+  return typeof value === "object" && value !== null;
+}
+function caseFold(value) {
+  return value.toLowerCase();
+}
+
 // packages/text2sql/src/lib/adapters/adapter.ts
 var Adapter = class {
   /**
@@ -133,10 +303,7 @@ var Adapter = class {
       const grounding = fn(this);
       await grounding.execute(ctx);
     }
-    return [
-      ...ctx.tables.map((t) => t.name),
-      ...ctx.views.map((v) => v.name)
-    ];
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
   }
   /**
    * Convert complete grounding context to schema fragments.
@@ -149,7 +316,8 @@ var Adapter = class {
         dialectInfo({
           dialect: ctx.info.dialect,
           version: ctx.info.version,
-          database: ctx.info.database
+          database: ctx.info.database,
+          details: ctx.info.details
         })
       );
     }
@@ -160,7 +328,18 @@ var Adapter = class {
       fragments.push(this.#viewToFragment(v));
     }
     const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    const tableColumnSets = new Map(
+      ctx.tables.map((t) => [t.name, new Set(t.columns.map((c) => c.name))])
+    );
     for (const rel of ctx.relationships) {
+      const sourceColumns = tableColumnSets.get(rel.table);
+      const targetColumns = tableColumnSets.get(rel.referenced_table);
+      if (sourceColumns && rel.from.some((column2) => !sourceColumns.has(column2))) {
+        continue;
+      }
+      if (targetColumns && rel.to.some((column2) => !targetColumns.has(column2))) {
+        continue;
+      }
       const sourceTable = tableMap.get(rel.table);
       const targetTable = tableMap.get(rel.referenced_table);
       fragments.push(
@@ -215,7 +394,10 @@ var Adapter = class {
         stats: col.stats
       })
     );
-    const indexFragments = (t.indexes ?? []).map(
+    const presentColumns = new Set(t.columns.map((c) => c.name));
+    const indexFragments = (t.indexes ?? []).filter(
+      (idx) => idx.columns.every((column2) => presentColumns.has(column2))
+    ).map(
       (idx) => index({
         name: idx.name,
         columns: idx.columns,
@@ -225,6 +407,8 @@ var Adapter = class {
     );
     const constraintFragments = (t.constraints ?? []).filter(
       (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).filter(
+      (c) => !c.columns?.length || c.columns.every((column2) => presentColumns.has(column2))
     ).map(
       (c) => constraint({
         name: c.name,
@@ -293,6 +477,78 @@ var Adapter = class {
       return sql;
     }
   }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #checkScope(sql, allowedEntities) {
+    const dialect = this.formatterLanguage;
+    const scopeDialects = {
+      sqlite: "mysql",
+      postgresql: "postgresql",
+      bigquery: "bigquery",
+      transactsql: "transactsql",
+      mysql: "mysql"
+    };
+    const scopeDialect = scopeDialects[dialect];
+    if (!scopeDialect) {
+      throw new TypeError(
+        `No scope dialect mapping for formatter language "${dialect}". Add it to the scopeDialects map in Adapter.#checkScope.`
+      );
+    }
+    let references;
+    try {
+      references = extractBaseEntityReferences(sql, scopeDialect);
+    } catch (error) {
+      return buildScopeParseErrorPayload(
+        sql,
+        dialect,
+        error
+      );
+    }
+    if (references.length === 0) return null;
+    const allowedQualified = new Set(
+      allowedEntities.map((e) => e.toLowerCase())
+    );
+    const allowedUnqualified = /* @__PURE__ */ new Set();
+    for (const entity of allowedEntities) {
+      const dot = entity.lastIndexOf(".");
+      if (dot !== -1) {
+        allowedUnqualified.add(entity.slice(dot + 1).toLowerCase());
+      } else {
+        allowedUnqualified.add(entity.toLowerCase());
+      }
+    }
+    const outOfScope = references.map((ref) => ref.db ? `${ref.db}.${ref.table}` : ref.table).filter((name) => {
+      const lower = name.toLowerCase();
+      if (name.includes(".")) {
+        if (allowedQualified.has(lower)) return false;
+        const parts = lower.split(".");
+        if (parts.length >= 3) {
+          const datasetTable = parts.slice(-2).join(".");
+          if (allowedQualified.has(datasetTable)) return false;
+        }
+        return true;
+      }
+      return !allowedQualified.has(lower) && !allowedUnqualified.has(lower);
+    });
+    if (outOfScope.length === 0) return null;
+    return buildOutOfScopePayload(sql, outOfScope, allowedEntities);
+  }
+  async validate(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) return JSON.stringify(scopeError);
+    return this.validateImpl(sql);
+  }
+  async execute(sql) {
+    const allowed = await this.#resolveScope();
+    const scopeError = await this.#checkScope(sql, allowed);
+    if (scopeError) throw new SQLScopeError(scopeError);
+    return this.executeImpl(sql);
+  }
   /**
    * Convert unknown database value to number.
    * Handles number, bigint, and string types.
@@ -413,48 +669,6 @@ function getTablesWithRelated(allTables, relationships, filter) {
   return Array.from(result);
 }
 
-// packages/text2sql/src/lib/agents/exceptions.ts
-var sqlValidationMarker = Symbol("SQLValidationError");
-var unanswerableSqlMarker = Symbol("UnanswerableSQLError");
-var sqlScopeMarker = Symbol("SQLScopeError");
-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;
-  }
-};
-
 // packages/text2sql/src/lib/agents/result-tools.ts
 import { tool } from "ai";
 import { createBashTool } from "bash-tool";
@@ -463,172 +677,17 @@ import {
   Bash,
   MountableFs,
   OverlayFs,
-  defineCommand,
-  parse
+  defineCommand
 } from "just-bash";
 import { AsyncLocalStorage } from "node:async_hooks";
-import * as path from "node:path";
+import * as path2 from "node:path";
 import { v7 } from "uuid";
 import z from "zod";
-function createCommand(name, subcommands) {
-  const usageLines = Object.entries(subcommands).map(([, def]) => `  ${name} ${def.usage.padEnd(30)} ${def.description}`).join("\n");
-  return defineCommand(name, async (args, ctx) => {
-    const subcommand = args[0];
-    const restArgs = args.slice(1);
-    if (subcommand && subcommand in subcommands) {
-      return subcommands[subcommand].handler(restArgs, ctx);
-    }
-    return {
-      stdout: "",
-      stderr: `${name}: ${subcommand ? `unknown subcommand '${subcommand}'` : "missing subcommand"}
 
-Usage:
-${usageLines}`,
-      exitCode: 1
-    };
-  });
-}
-function validateReadOnly(query) {
-  const upper = query.toUpperCase().trim();
-  if (!upper.startsWith("SELECT") && !upper.startsWith("WITH")) {
-    return { valid: false, error: "only SELECT or WITH queries allowed" };
-  }
-  return { valid: true };
-}
-var SQL_VALIDATE_REMINDER = "Always run `sql validate` before `sql run` to catch syntax errors early.";
-function createSqlCommand(adapter, metaStore) {
-  return createCommand("sql", {
-    run: {
-      usage: 'run "SELECT ..."',
-      description: "Execute query and store results",
-      handler: async (args, ctx) => {
-        const store = metaStore.getStore();
-        if (store) {
-          store.value = { ...store.value, reminder: SQL_VALIDATE_REMINDER };
-        }
-        const rawQuery = args.join(" ").trim().replace(/\\n/g, "\n").replace(/\\t/g, "	");
-        if (!rawQuery) {
-          return {
-            stdout: "",
-            stderr: "sql run: no query provided",
-            exitCode: 1
-          };
-        }
-        const validation = validateReadOnly(rawQuery);
-        if (!validation.valid) {
-          return {
-            stdout: "",
-            stderr: `sql run: ${validation.error}`,
-            exitCode: 1
-          };
-        }
-        const query = adapter.format(rawQuery);
-        if (store) {
-          store.value = { ...store.value, formattedSql: query };
-        }
-        const syntaxError = await adapter.validate(query);
-        if (syntaxError) {
-          return {
-            stdout: "",
-            stderr: `sql run: ${syntaxError}`,
-            exitCode: 1
-          };
-        }
-        try {
-          const rows = await adapter.execute(query);
-          const rowsArray = Array.isArray(rows) ? rows : [];
-          const content = JSON.stringify(rowsArray, null, 2);
-          const filename = `${v7()}.json`;
-          const sqlPath = `/sql/${filename}`;
-          await ctx.fs.mkdir("/sql", { recursive: true });
-          await ctx.fs.writeFile(sqlPath, content);
-          const columns = rowsArray.length > 0 ? Object.keys(rowsArray[0]) : [];
-          return {
-            stdout: [
-              `results stored in ${sqlPath}`,
-              `columns: ${columns.join(", ") || "(none)"}`,
-              `rows: ${rowsArray.length}`
-            ].join("\n") + "\n",
-            stderr: "",
-            exitCode: 0
-          };
-        } catch (error) {
-          return {
-            stdout: "",
-            stderr: `sql run: ${error instanceof Error ? error.message : String(error)}`,
-            exitCode: 1
-          };
-        }
-      }
-    },
-    validate: {
-      usage: 'validate "SELECT ..."',
-      description: "Validate query syntax",
-      handler: async (args) => {
-        const rawQuery = args.join(" ").trim().replace(/\\n/g, "\n").replace(/\\t/g, "	");
-        if (!rawQuery) {
-          return {
-            stdout: "",
-            stderr: "sql validate: no query provided",
-            exitCode: 1
-          };
-        }
-        const validation = validateReadOnly(rawQuery);
-        if (!validation.valid) {
-          return {
-            stdout: "",
-            stderr: `sql validate: ${validation.error}`,
-            exitCode: 1
-          };
-        }
-        const query = adapter.format(rawQuery);
-        const store = metaStore.getStore();
-        if (store) store.value = { ...store.value, formattedSql: query };
-        const syntaxError = await adapter.validate(query);
-        if (syntaxError) {
-          return {
-            stdout: "",
-            stderr: `sql validate: ${syntaxError}`,
-            exitCode: 1
-          };
-        }
-        return {
-          stdout: "valid\n",
-          stderr: "",
-          exitCode: 0
-        };
-      }
-    }
-  });
-}
-var BLOCKED_DB_CLIENT_COMMANDS = /* @__PURE__ */ new Set([
-  "psql",
-  "sqlite3",
-  "mysql",
-  "duckdb"
-]);
-var BLOCKED_RAW_SQL_COMMANDS = /* @__PURE__ */ new Set(["select", "with"]);
-var ALLOWED_SQL_PROXY_SUBCOMMANDS = /* @__PURE__ */ new Set(["run", "validate"]);
-var SHELL_INTERPRETER_COMMANDS = /* @__PURE__ */ new Set([
-  "bash",
-  "sh",
-  "zsh",
-  "dash",
-  "ksh"
-]);
-var WRAPPER_COMMANDS = /* @__PURE__ */ new Set(["env", "command", "eval"]);
-var SQL_PROXY_ENFORCEMENT_MESSAGE = [
-  "Direct database querying through bash is blocked.",
-  "Use SQL proxy commands in this order:",
-  '1) sql validate "SELECT ..."',
-  '2) sql run "SELECT ..."'
-].join("\n");
-function cloneInspectionContext(context) {
-  return {
-    functionDefinitions: new Map(context.functionDefinitions),
-    callStack: new Set(context.callStack)
-  };
-}
+// packages/text2sql/src/lib/agents/sql-transform-plugins.ts
+import { parse, serialize } from "just-bash";
+import { createHash } from "node:crypto";
+import * as path from "node:path";
 function asStaticWordText(word) {
   if (!word) {
     return null;
@@ -672,6 +731,40 @@ function isScriptNode(value) {
   const node = value;
   return node.type === "Script" && Array.isArray(node.statements);
 }
+var BLOCKED_DB_CLIENT_COMMANDS = /* @__PURE__ */ new Set([
+  "psql",
+  "sqlite3",
+  "mysql",
+  "duckdb"
+]);
+var BLOCKED_RAW_SQL_COMMANDS = /* @__PURE__ */ new Set(["select", "with"]);
+var ALLOWED_SQL_PROXY_SUBCOMMANDS = /* @__PURE__ */ new Set(["run", "validate"]);
+var SHELL_INTERPRETER_COMMANDS = /* @__PURE__ */ new Set([
+  "bash",
+  "sh",
+  "zsh",
+  "dash",
+  "ksh"
+]);
+var WRAPPER_COMMANDS = /* @__PURE__ */ new Set(["env", "command", "eval"]);
+var SQL_PROXY_ENFORCEMENT_MESSAGE = [
+  "Direct database querying through bash is blocked.",
+  "Use SQL proxy commands in this order:",
+  '1) sql validate "SELECT ..."',
+  '2) sql run "SELECT ..."'
+].join("\n");
+var SqlProxyViolationError = class extends Error {
+  constructor() {
+    super(SQL_PROXY_ENFORCEMENT_MESSAGE);
+    this.name = "SqlProxyViolationError";
+  }
+};
+function cloneInspectionContext(context) {
+  return {
+    functionDefinitions: new Map(context.functionDefinitions),
+    callStack: new Set(context.callStack)
+  };
+}
 function scriptContainsBlockedCommand(script, context, mode = "blocked-only") {
   return statementsContainBlockedCommand(script.statements, context, mode);
 }
@@ -1236,39 +1329,288 @@ function isBlockedSimpleCommand(command, context, mode, options) {
   }
   return false;
 }
-function getSqlProxyEnforcementResult(command) {
-  const trimmed = command.trim();
-  if (!trimmed) {
-    return null;
+var SqlProxyEnforcementPlugin = class {
+  name = "sql-proxy-enforcement";
+  transform(context) {
+    const blocked = scriptContainsBlockedCommand(context.ast, {
+      functionDefinitions: /* @__PURE__ */ new Map(),
+      callStack: /* @__PURE__ */ new Set()
+    });
+    if (blocked) {
+      throw new SqlProxyViolationError();
+    }
+    return {
+      ast: context.ast,
+      metadata: { inspected: true }
+    };
   }
-  let script;
-  try {
-    script = parse(trimmed);
-  } catch {
-    return null;
+};
+function wordPartsContainBacktickSubstitution(parts) {
+  for (const part of parts) {
+    if (part.type === "CommandSubstitution" && part.legacy === true) {
+      return true;
+    }
+    if (part.type === "DoubleQuoted" && Array.isArray(part.parts)) {
+      if (wordPartsContainBacktickSubstitution(
+        part.parts
+      )) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function isSqlBacktickCommand(cmd) {
+  if (cmd.type !== "SimpleCommand") return false;
+  if (cmd.assignments.length > 0 || cmd.redirections.length > 0) return false;
+  if (asStaticWordText(cmd.name) !== "sql") return false;
+  if (cmd.args.length < 2) return false;
+  const subcommand = asStaticWordText(cmd.args[0]);
+  if (subcommand !== "validate" && subcommand !== "run") return false;
+  const sqlArgs = cmd.args.slice(1);
+  return sqlArgs.some(
+    (arg) => wordPartsContainBacktickSubstitution(
+      arg.parts
+    )
+  );
+}
+function extractWordPartText(parts) {
+  let text = "";
+  for (const part of parts) {
+    const type = part.type;
+    if (type === "Literal" || type === "SingleQuoted" || type === "Escaped") {
+      text += part.value;
+    } else if (type === "DoubleQuoted" && Array.isArray(part.parts)) {
+      text += extractWordPartText(part.parts);
+    } else if (type === "CommandSubstitution" && part.legacy === true) {
+      text += "`" + serialize(part.body).trim() + "`";
+    }
+  }
+  return text;
+}
+function extractSqlText(args) {
+  return args.map(
+    (arg) => extractWordPartText(
+      arg.parts
+    )
+  ).join(" ");
+}
+function rewriteSqlBacktickCommand(cmd, ast) {
+  const subcommand = asStaticWordText(cmd.args[0]);
+  const sqlArgs = cmd.args.slice(1);
+  const unquotedSql = extractSqlText(sqlArgs);
+  const hash2 = createHash("sha256").update(serialize(ast)).digest("hex").slice(0, 12);
+  const sqlPath = `/tmp/sql-inline-${subcommand}-${hash2}.sql`;
+  const heredocTag = `SQL_${hash2.toUpperCase()}`;
+  const groupScript = [
+    `{ cat > ${sqlPath} <<'${heredocTag}'`,
+    unquotedSql,
+    heredocTag,
+    `sql ${subcommand} "$(cat ${sqlPath})"; }`
+  ].join("\n");
+  const groupAst = parse(groupScript);
+  return groupAst.statements[0].pipelines[0].commands[0];
+}
+function rewriteBackticksInCommands(commands, ast) {
+  let rewritten = false;
+  for (let i = 0; i < commands.length; i++) {
+    const cmd = commands[i];
+    if (isSqlBacktickCommand(cmd)) {
+      commands[i] = rewriteSqlBacktickCommand(cmd, ast);
+      rewritten = true;
+      continue;
+    }
+    if (cmd.type === "If") {
+      for (const clause of cmd.clauses) {
+        if (rewriteBackticksInStatements(clause.condition, ast))
+          rewritten = true;
+        if (rewriteBackticksInStatements(clause.body, ast)) rewritten = true;
+      }
+      if (cmd.elseBody && rewriteBackticksInStatements(cmd.elseBody, ast)) {
+        rewritten = true;
+      }
+    } else if (cmd.type === "While" || cmd.type === "Until") {
+      if (rewriteBackticksInStatements(cmd.condition, ast)) rewritten = true;
+      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
+    } else if (cmd.type === "For" || cmd.type === "CStyleFor") {
+      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
+    } else if (cmd.type === "Case") {
+      for (const item of cmd.items) {
+        if (rewriteBackticksInStatements(item.body, ast)) rewritten = true;
+      }
+    } else if (cmd.type === "Subshell" || cmd.type === "Group") {
+      if (rewriteBackticksInStatements(cmd.body, ast)) rewritten = true;
+    }
+  }
+  return rewritten;
+}
+function rewriteBackticksInStatements(statements, ast) {
+  let rewritten = false;
+  for (const statement of statements) {
+    for (const pipeline of statement.pipelines) {
+      if (rewriteBackticksInCommands(pipeline.commands, ast)) {
+        rewritten = true;
+      }
+    }
   }
-  const blocked = scriptContainsBlockedCommand(script, {
-    functionDefinitions: /* @__PURE__ */ new Map(),
-    callStack: /* @__PURE__ */ new Set()
+  return rewritten;
+}
+var SqlBacktickRewritePlugin = class {
+  name = "sql-backtick-rewrite";
+  transform(context) {
+    const ast = context.ast;
+    const rewritten = rewriteBackticksInStatements(ast.statements, ast);
+    return { ast, metadata: { rewritten } };
+  }
+};
+
+// packages/text2sql/src/lib/agents/result-tools.ts
+function createCommand(name, subcommands) {
+  const usageLines = Object.entries(subcommands).map(([, def]) => `  ${name} ${def.usage.padEnd(30)} ${def.description}`).join("\n");
+  return defineCommand(name, async (args, ctx) => {
+    const subcommand = args[0];
+    const restArgs = args.slice(1);
+    if (subcommand && subcommand in subcommands) {
+      return subcommands[subcommand].handler(restArgs, ctx);
+    }
+    return {
+      stdout: "",
+      stderr: `${name}: ${subcommand ? `unknown subcommand '${subcommand}'` : "missing subcommand"}
+
+Usage:
+${usageLines}`,
+      exitCode: 1
+    };
   });
-  if (!blocked) {
-    return null;
+}
+function validateReadOnly(query) {
+  const upper = query.toUpperCase().trim();
+  if (!upper.startsWith("SELECT") && !upper.startsWith("WITH")) {
+    return { valid: false, error: "only SELECT or WITH queries allowed" };
   }
-  return {
-    stdout: "",
-    stderr: `${SQL_PROXY_ENFORCEMENT_MESSAGE}
-`,
-    exitCode: 1
-  };
+  return { valid: true };
+}
+var SQL_VALIDATE_REMINDER = "Always run `sql validate` before `sql run` to catch syntax errors early.";
+function createSqlCommand(adapter, metaStore) {
+  return createCommand("sql", {
+    run: {
+      usage: 'run "SELECT ..."',
+      description: "Execute query and store results",
+      handler: async (args, ctx) => {
+        const store = metaStore.getStore();
+        if (store) {
+          store.value = { ...store.value, reminder: SQL_VALIDATE_REMINDER };
+        }
+        const rawQuery = args.join(" ").trim().replace(/\\n/g, "\n").replace(/\\t/g, "	");
+        if (!rawQuery) {
+          return {
+            stdout: "",
+            stderr: "sql run: no query provided",
+            exitCode: 1
+          };
+        }
+        const validation = validateReadOnly(rawQuery);
+        if (!validation.valid) {
+          return {
+            stdout: "",
+            stderr: `sql run: ${validation.error}`,
+            exitCode: 1
+          };
+        }
+        const query = adapter.format(rawQuery);
+        if (store) {
+          store.value = { ...store.value, formattedSql: query };
+        }
+        const syntaxError = await adapter.validate(query);
+        if (syntaxError) {
+          return {
+            stdout: "",
+            stderr: `sql run: ${syntaxError}`,
+            exitCode: 1
+          };
+        }
+        try {
+          const rows = await adapter.execute(query);
+          const rowsArray = Array.isArray(rows) ? rows : [];
+          const content = JSON.stringify(rowsArray, null, 2);
+          const filename = `${v7()}.json`;
+          const sqlPath = `/sql/${filename}`;
+          await ctx.fs.mkdir("/sql", { recursive: true });
+          await ctx.fs.writeFile(sqlPath, content);
+          const columns = rowsArray.length > 0 ? Object.keys(rowsArray[0]) : [];
+          return {
+            stdout: [
+              `results stored in ${sqlPath}`,
+              `columns: ${columns.join(", ") || "(none)"}`,
+              `rows: ${rowsArray.length}`
+            ].join("\n") + "\n",
+            stderr: "",
+            exitCode: 0
+          };
+        } catch (error) {
+          return {
+            stdout: "",
+            stderr: `sql run: ${error instanceof Error ? error.message : String(error)}`,
+            exitCode: 1
+          };
+        }
+      }
+    },
+    validate: {
+      usage: 'validate "SELECT ..."',
+      description: "Validate query syntax",
+      handler: async (args) => {
+        const rawQuery = args.join(" ").trim().replace(/\\n/g, "\n").replace(/\\t/g, "	");
+        if (!rawQuery) {
+          return {
+            stdout: "",
+            stderr: "sql validate: no query provided",
+            exitCode: 1
+          };
+        }
+        const validation = validateReadOnly(rawQuery);
+        if (!validation.valid) {
+          return {
+            stdout: "",
+            stderr: `sql validate: ${validation.error}`,
+            exitCode: 1
+          };
+        }
+        const query = adapter.format(rawQuery);
+        const store = metaStore.getStore();
+        if (store) store.value = { ...store.value, formattedSql: query };
+        const syntaxError = await adapter.validate(query);
+        if (syntaxError) {
+          return {
+            stdout: "",
+            stderr: `sql validate: ${syntaxError}`,
+            exitCode: 1
+          };
+        }
+        return {
+          stdout: "valid\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+    }
+  });
+}
+function toViolationResult(error) {
+  if (error instanceof SqlProxyViolationError) {
+    return { stdout: "", stderr: `${error.message}
+`, exitCode: 1 };
+  }
+  return null;
 }
 async function createResultTools(options) {
   const { adapter, skillMounts, filesystem: baseFs } = options;
   const metaStore = new AsyncLocalStorage();
   const sqlCommand = createSqlCommand(adapter, metaStore);
   const fsMounts = skillMounts.map(({ host, sandbox: sandbox2 }) => ({
-    mountPoint: path.dirname(sandbox2),
+    mountPoint: path2.dirname(sandbox2),
     filesystem: new OverlayFs({
-      root: path.dirname(host),
+      root: path2.dirname(host),
       mountPoint: "/",
       readOnly: true
     })
@@ -1281,6 +1623,8 @@ async function createResultTools(options) {
     customCommands: [sqlCommand],
     fs: filesystem
   });
+  bashInstance.registerTransformPlugin(new SqlBacktickRewritePlugin());
+  bashInstance.registerTransformPlugin(new SqlProxyEnforcementPlugin());
   const { sandbox, tools } = await createBashTool({
     sandbox: bashInstance,
     destination: "/",
@@ -1299,11 +1643,13 @@ async function createResultTools(options) {
   const guardedSandbox = {
     ...sandbox,
     executeCommand: async (command) => {
-      const blockedResult = getSqlProxyEnforcementResult(command);
-      if (blockedResult) {
-        return blockedResult;
+      try {
+        return await sandbox.executeCommand(command);
+      } catch (error) {
+        const violation = toViolationResult(error);
+        if (violation) return violation;
+        throw error;
       }
-      return sandbox.executeCommand(command);
     }
   };
   const bash = tool({
@@ -1317,16 +1663,18 @@ async function createResultTools(options) {
       if (!execute) {
         throw new Error("bash tool execution is not available");
       }
-      const blockedResult = getSqlProxyEnforcementResult(command);
-      if (blockedResult) {
-        return blockedResult;
-      }
       return metaStore.run({}, async () => {
-        const result = await execute({ command }, execOptions);
-        const storeValue = metaStore.getStore()?.value;
-        if (!storeValue) return result;
-        const { reminder, ...meta } = storeValue;
-        return { ...result, meta, reminder };
+        try {
+          const result = await execute({ command }, execOptions);
+          const storeValue = metaStore.getStore()?.value;
+          if (!storeValue) return result;
+          const { reminder, ...meta } = storeValue;
+          return { ...result, meta, reminder };
+        } catch (error) {
+          const violation = toViolationResult(error);
+          if (violation) return violation;
+          throw error;
+        }
       });
     },
     toModelOutput: ({ output }) => {
@@ -1812,16 +2160,16 @@ var suggestionsAgent = agent({
 });
 
 // packages/text2sql/src/lib/checkpoint.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import pLimit from "p-limit";
 var Checkpoint = class _Checkpoint {
   points;
   path;
   configHash;
-  constructor(path6, configHash, points) {
+  constructor(path7, configHash, points) {
     this.points = points;
-    this.path = path6;
+    this.path = path7;
     this.configHash = configHash;
   }
   /**
@@ -1829,14 +2177,14 @@ var Checkpoint = class _Checkpoint {
    * Handles corrupted files and config changes gracefully.
    */
   static async load(options) {
-    const { path: path6, configHash } = options;
-    if (existsSync(path6)) {
+    const { path: path7, configHash } = options;
+    if (existsSync(path7)) {
       try {
-        const content = readFileSync(path6, "utf-8");
+        const content = readFileSync(path7, "utf-8");
         const file = JSON.parse(content);
         if (configHash && file.configHash && file.configHash !== configHash) {
           console.log("\u26A0 Config changed, starting fresh");
-          return new _Checkpoint(path6, configHash, {});
+          return new _Checkpoint(path7, configHash, {});
         }
         const points = file.points ?? {};
         const totalEntries = Object.values(points).reduce(
@@ -1844,14 +2192,14 @@ var Checkpoint = class _Checkpoint {
           0
         );
         console.log(`\u2713 Resuming from checkpoint (${totalEntries} entries)`);
-        return new _Checkpoint(path6, configHash, points);
+        return new _Checkpoint(path7, configHash, points);
       } catch {
         console.log("\u26A0 Checkpoint corrupted, starting fresh");
-        return new _Checkpoint(path6, configHash, {});
+        return new _Checkpoint(path7, configHash, {});
       }
     }
     console.log("Starting new checkpoint");
-    return new _Checkpoint(path6, configHash, {});
+    return new _Checkpoint(path7, configHash, {});
   }
   /**
    * Run a single computation with checkpointing.
@@ -1933,7 +2281,7 @@ var Checkpoint = class _Checkpoint {
   }
 };
 function hash(value) {
-  return createHash("md5").update(JSON.stringify(value)).digest("hex");
+  return createHash2("md5").update(JSON.stringify(value)).digest("hex");
 }
 var Point = class {
   #cache;
@@ -1977,20 +2325,20 @@ var Point = class {
   }
 };
 function hashConfig(config) {
-  return createHash("md5").update(JSON.stringify(config)).digest("hex");
+  return createHash2("md5").update(JSON.stringify(config)).digest("hex");
 }
 
 // packages/text2sql/src/lib/file-cache.ts
-import { createHash as createHash2 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { existsSync as existsSync2 } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import path2 from "node:path";
+import path3 from "node:path";
 var FileCache = class {
   path;
   constructor(watermark, extension = ".txt") {
-    const hash2 = createHash2("md5").update(watermark).digest("hex");
-    this.path = path2.join(tmpdir(), `text2sql-${hash2}${extension}`);
+    const hash2 = createHash3("md5").update(watermark).digest("hex");
+    this.path = path3.join(tmpdir(), `text2sql-${hash2}${extension}`);
   }
   async get() {
     if (existsSync2(this.path)) {
@@ -2019,7 +2367,7 @@ var JsonCache = class extends FileCache {
 };
 
 // packages/text2sql/src/lib/fs/sqlite/sqlite-fs.ts
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 import { DatabaseSync } from "node:sqlite";
 
 // packages/text2sql/src/lib/fs/sqlite/ddl.sqlite-fs.sql
@@ -2067,7 +2415,7 @@ var SqliteFs = class {
     const segments = p.split("/").filter(Boolean);
     let currentPath = "/";
     for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path3.posix.join(currentPath, segments[i]);
+      currentPath = path4.posix.join(currentPath, segments[i]);
       const exists = this.#stmt("SELECT 1 FROM fs_entries WHERE path = ?").get(
         currentPath
       );
@@ -2088,7 +2436,7 @@ var SqliteFs = class {
     return stmt;
   }
   #normalizeRoot(root) {
-    return path3.posix.resolve("/", root.trim());
+    return path4.posix.resolve("/", root.trim());
   }
   #prefixPath(p) {
     if (!this.#root) {
@@ -2097,7 +2445,7 @@ var SqliteFs = class {
     if (p === "/") {
       return this.#root;
     }
-    return path3.posix.join(this.#root, p);
+    return path4.posix.join(this.#root, p);
   }
   #unprefixPath(p) {
     if (!this.#root) {
@@ -2123,10 +2471,10 @@ var SqliteFs = class {
     }
   }
   #normalizePath(p) {
-    return path3.posix.resolve("/", p);
+    return path4.posix.resolve("/", p);
   }
   #dirname(p) {
-    const dir = path3.posix.dirname(p);
+    const dir = path4.posix.dirname(p);
     return dir === "" ? "/" : dir;
   }
   #ensureParentExists(filePath) {
@@ -2189,7 +2537,7 @@ var SqliteFs = class {
     }
     seen.add(p);
     const target = this.#normalizePath(
-      path3.posix.resolve(this.#dirname(p), entry.symlinkTarget)
+      path4.posix.resolve(this.#dirname(p), entry.symlinkTarget)
     );
     return this.#resolveSymlink(target, seen);
   }
@@ -2341,11 +2689,11 @@ var SqliteFs = class {
     this.#useTransaction(() => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path3.posix.relative(rootPath, prefixed);
+        const relativePath = path4.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path3.posix.join(currentPath, segment);
+          currentPath = path4.posix.join(currentPath, segment);
           const exists = this.#stmt(
             "SELECT type FROM fs_entries WHERE path = ?"
           ).get(currentPath);
@@ -2396,7 +2744,7 @@ var SqliteFs = class {
          AND path != ?
          AND path NOT LIKE ? || '%/%'`
     ).all(prefix, resolved, prefix);
-    return rows.map((row) => path3.posix.basename(row.path));
+    return rows.map((row) => path4.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -2419,7 +2767,7 @@ var SqliteFs = class {
          AND path NOT LIKE ? || '%/%'`
     ).all(prefix, resolved, prefix);
     return rows.map((row) => ({
-      name: path3.posix.basename(row.path),
+      name: path4.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -2474,8 +2822,8 @@ var SqliteFs = class {
           `SELECT * FROM fs_entries WHERE path = ? OR path LIKE ? || '/%'`
         ).all(srcPrefixed, srcPrefixed);
         for (const entry of allEntries) {
-          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
-          const newPath = path3.posix.join(destPrefixed, relativePath);
+          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
+          const newPath = path4.posix.join(destPrefixed, relativePath);
           this.#stmt(
             `INSERT OR REPLACE INTO fs_entries (path, type, mode, size, mtime, symlinkTarget)
              VALUES (?, ?, ?, ?, ?, ?)`
@@ -2542,8 +2890,8 @@ var SqliteFs = class {
           `SELECT * FROM fs_entries WHERE path = ? OR path LIKE ? || '/%' ORDER BY path DESC`
         ).all(srcPrefixed, srcPrefixed);
         for (const entry of [...allEntries].reverse()) {
-          const relativePath = path3.posix.relative(srcPrefixed, entry.path);
-          const newPath = path3.posix.join(destPrefixed, relativePath);
+          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
+          const newPath = path4.posix.join(destPrefixed, relativePath);
           this.#stmt(
             `INSERT INTO fs_entries (path, type, mode, size, mtime, symlinkTarget)
              VALUES (?, ?, ?, ?, ?, ?)`
@@ -2596,7 +2944,7 @@ var SqliteFs = class {
     });
   }
   resolvePath(base, relativePath) {
-    return path3.posix.resolve(base, relativePath);
+    return path4.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     const rows = this.#stmt(
@@ -2708,7 +3056,7 @@ var SqliteFs = class {
 
 // packages/text2sql/src/lib/fs/mssql/mssql-fs.ts
 import { createRequire } from "node:module";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 
 // packages/text2sql/src/lib/fs/mssql/ddl.mssql-fs.ts
 function mssqlFsDDL(schema) {
@@ -2834,7 +3182,7 @@ var MssqlFs = class _MssqlFs {
     const segments = p.split("/").filter(Boolean);
     let currentPath = "/";
     for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path4.posix.join(currentPath, segments[i]);
+      currentPath = path5.posix.join(currentPath, segments[i]);
       const exists = await this.#rawQuery(
         `SELECT CASE WHEN EXISTS(SELECT 1 FROM ${this.#t("fs_entries")} WHERE path = @p0) THEN 1 ELSE 0 END as [exists]`,
         [currentPath]
@@ -2886,7 +3234,7 @@ var MssqlFs = class _MssqlFs {
     }
   }
   #normalizeRoot(root) {
-    return path4.posix.resolve("/", root.trim());
+    return path5.posix.resolve("/", root.trim());
   }
   #prefixPath(p) {
     if (!this.#root) {
@@ -2895,7 +3243,7 @@ var MssqlFs = class _MssqlFs {
     if (p === "/") {
       return this.#root;
     }
-    return path4.posix.join(this.#root, p);
+    return path5.posix.join(this.#root, p);
   }
   #unprefixPath(p) {
     if (!this.#root) {
@@ -2910,10 +3258,10 @@ var MssqlFs = class _MssqlFs {
     return p;
   }
   #normalizePath(p) {
-    return path4.posix.resolve("/", p);
+    return path5.posix.resolve("/", p);
   }
   #dirname(p) {
-    const dir = path4.posix.dirname(p);
+    const dir = path5.posix.dirname(p);
     return dir === "" ? "/" : dir;
   }
   async #ensureParentExists(filePath, transaction) {
@@ -3002,7 +3350,7 @@ var MssqlFs = class _MssqlFs {
     }
     seen.add(p);
     const target = this.#normalizePath(
-      path4.posix.resolve(this.#dirname(p), entry.symlinkTarget)
+      path5.posix.resolve(this.#dirname(p), entry.symlinkTarget)
     );
     return this.#resolveSymlink(target, seen);
   }
@@ -3185,11 +3533,11 @@ var MssqlFs = class _MssqlFs {
     await this.#useTransaction(async (transaction) => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path4.posix.relative(rootPath, prefixed);
+        const relativePath = path5.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path4.posix.join(currentPath, segment);
+          currentPath = path5.posix.join(currentPath, segment);
           const checkReq = transaction.request();
           checkReq.input("p0", currentPath);
           const result = await checkReq.query(
@@ -3253,7 +3601,7 @@ var MssqlFs = class _MssqlFs {
          AND path NOT LIKE @p0 + '%/%'`,
       [prefix, resolved]
     );
-    return rows.map((row) => path4.posix.basename(row.path));
+    return rows.map((row) => path5.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -3279,7 +3627,7 @@ var MssqlFs = class _MssqlFs {
       [prefix, resolved]
     );
     return rows.map((row) => ({
-      name: path4.posix.basename(row.path),
+      name: path5.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -3348,8 +3696,8 @@ var MssqlFs = class _MssqlFs {
           `SELECT * FROM ${this.#t("fs_entries")} WHERE path = @p0 OR path LIKE @p0 + '/%'`
         );
         for (const entry of allEntriesResult.recordset) {
-          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
-          const newPath = path4.posix.join(destPrefixed, relativePath);
+          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
+          const newPath = path5.posix.join(destPrefixed, relativePath);
           const insertReq = transaction.request();
           insertReq.input("p0", newPath);
           insertReq.input("p1", entry.type);
@@ -3458,8 +3806,8 @@ var MssqlFs = class _MssqlFs {
           `DELETE FROM ${this.#t("fs_entries")} WHERE path = @dp0 OR path LIKE @dp0 + '/%'`
         );
         for (const entry of [...allEntriesResult.recordset].reverse()) {
-          const relativePath = path4.posix.relative(srcPrefixed, entry.path);
-          const newPath = path4.posix.join(destPrefixed, relativePath);
+          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
+          const newPath = path5.posix.join(destPrefixed, relativePath);
           const insertReq = transaction.request();
           insertReq.input("p0", newPath);
           insertReq.input("p1", entry.type);
@@ -3552,7 +3900,7 @@ var MssqlFs = class _MssqlFs {
     });
   }
   resolvePath(base, relativePath) {
-    return path4.posix.resolve(base, relativePath);
+    return path5.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     throw new Error(
@@ -3693,7 +4041,7 @@ var MssqlFs = class _MssqlFs {
 
 // packages/text2sql/src/lib/fs/postgres/postgres-fs.ts
 import { createRequire as createRequire2 } from "node:module";
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 
 // packages/text2sql/src/lib/fs/postgres/ddl.postgres-fs.ts
 function postgresFsDDL(schema) {
@@ -3798,7 +4146,7 @@ var PostgresFs = class _PostgresFs {
     const segments = p.split("/").filter(Boolean);
     let currentPath = "/";
     for (let i = 0; i < segments.length - 1; i++) {
-      currentPath = path5.posix.join(currentPath, segments[i]);
+      currentPath = path6.posix.join(currentPath, segments[i]);
       const exists = await this.#rawQuery(
         `SELECT EXISTS(SELECT 1 FROM ${this.#t("fs_entries")} WHERE path = $1) AS exists`,
         [currentPath]
@@ -3843,7 +4191,7 @@ var PostgresFs = class _PostgresFs {
     }
   }
   #normalizeRoot(root) {
-    return path5.posix.resolve("/", root.trim());
+    return path6.posix.resolve("/", root.trim());
   }
   #prefixPath(p) {
     if (!this.#root) {
@@ -3852,7 +4200,7 @@ var PostgresFs = class _PostgresFs {
     if (p === "/") {
       return this.#root;
     }
-    return path5.posix.join(this.#root, p);
+    return path6.posix.join(this.#root, p);
   }
   #unprefixPath(p) {
     if (!this.#root) {
@@ -3867,10 +4215,10 @@ var PostgresFs = class _PostgresFs {
     return p;
   }
   #normalizePath(p) {
-    return path5.posix.resolve("/", p);
+    return path6.posix.resolve("/", p);
   }
   #dirname(p) {
-    const dir = path5.posix.dirname(p);
+    const dir = path6.posix.dirname(p);
     return dir === "" ? "/" : dir;
   }
   async #ensureParentExists(filePath, client) {
@@ -3950,7 +4298,7 @@ var PostgresFs = class _PostgresFs {
     }
     seen.add(p);
     const target = this.#normalizePath(
-      path5.posix.resolve(this.#dirname(p), entry.symlink_target)
+      path6.posix.resolve(this.#dirname(p), entry.symlink_target)
     );
     return this.#resolveSymlink(target, seen);
   }
@@ -4116,11 +4464,11 @@ var PostgresFs = class _PostgresFs {
     await this.#useTransaction(async (client) => {
       if (options?.recursive) {
         const rootPath = this.#root || "/";
-        const relativePath = path5.posix.relative(rootPath, prefixed);
+        const relativePath = path6.posix.relative(rootPath, prefixed);
         const segments = relativePath.split("/").filter(Boolean);
         let currentPath = rootPath;
         for (const segment of segments) {
-          currentPath = path5.posix.join(currentPath, segment);
+          currentPath = path6.posix.join(currentPath, segment);
           const result = await client.query(
             `SELECT type FROM ${this.#t("fs_entries")} WHERE path = $1`,
             [currentPath]
@@ -4178,7 +4526,7 @@ var PostgresFs = class _PostgresFs {
          AND path NOT LIKE $1 || '%/%'`,
       [prefix, resolved]
     );
-    return rows.map((row) => path5.posix.basename(row.path));
+    return rows.map((row) => path6.posix.basename(row.path));
   }
   async readdirWithFileTypes(dirPath) {
     const normalized = this.#normalizePath(dirPath);
@@ -4204,7 +4552,7 @@ var PostgresFs = class _PostgresFs {
       [prefix, resolved]
     );
     return rows.map((row) => ({
-      name: path5.posix.basename(row.path),
+      name: path6.posix.basename(row.path),
       isFile: row.type === "file",
       isDirectory: row.type === "directory",
       isSymbolicLink: row.type === "symlink"
@@ -4269,8 +4617,8 @@ var PostgresFs = class _PostgresFs {
           [srcPrefixed]
         );
         for (const entry of allEntriesResult.rows) {
-          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
-          const newPath = path5.posix.join(destPrefixed, relativePath);
+          const relativePath = path6.posix.relative(srcPrefixed, entry.path);
+          const newPath = path6.posix.join(destPrefixed, relativePath);
           await client.query(
             `INSERT INTO ${this.#t("fs_entries")} (path, type, mode, size, mtime, symlink_target)
              VALUES ($1, $2, $3, $4, $5, $6)
@@ -4359,8 +4707,8 @@ var PostgresFs = class _PostgresFs {
           [destPrefixed]
         );
         for (const entry of [...allEntriesResult.rows].reverse()) {
-          const relativePath = path5.posix.relative(srcPrefixed, entry.path);
-          const newPath = path5.posix.join(destPrefixed, relativePath);
+          const relativePath = path6.posix.relative(srcPrefixed, entry.path);
+          const newPath = path6.posix.join(destPrefixed, relativePath);
           await client.query(
             `INSERT INTO ${this.#t("fs_entries")} (path, type, mode, size, mtime, symlink_target)
              VALUES ($1, $2, $3, $4, $5, $6)
@@ -4433,7 +4781,7 @@ var PostgresFs = class _PostgresFs {
     });
   }
   resolvePath(base, relativePath) {
-    return path5.posix.resolve(base, relativePath);
+    return path6.posix.resolve(base, relativePath);
   }
   getAllPaths() {
     throw new Error(
@@ -4569,29 +4917,29 @@ var ScopedFs = class {
     this.#base = options.base;
     this.#prefix = options.prefix.replace(/\/$/, "");
   }
-  #scope(path6) {
-    return `${this.#prefix}${path6}`;
+  #scope(path7) {
+    return `${this.#prefix}${path7}`;
   }
-  #unscope(path6) {
-    if (path6 === this.#prefix) {
+  #unscope(path7) {
+    if (path7 === this.#prefix) {
       return "/";
     }
-    if (path6.startsWith(this.#prefix + "/")) {
-      return path6.slice(this.#prefix.length) || "/";
+    if (path7.startsWith(this.#prefix + "/")) {
+      return path7.slice(this.#prefix.length) || "/";
     }
-    return path6;
+    return path7;
   }
-  async writeFile(path6, content, options) {
-    await this.#base.writeFile(this.#scope(path6), content, options);
+  async writeFile(path7, content, options) {
+    await this.#base.writeFile(this.#scope(path7), content, options);
   }
-  async appendFile(path6, content, options) {
-    await this.#base.appendFile(this.#scope(path6), content, options);
+  async appendFile(path7, content, options) {
+    await this.#base.appendFile(this.#scope(path7), content, options);
   }
-  async mkdir(path6, options) {
-    return this.#base.mkdir(this.#scope(path6), options);
+  async mkdir(path7, options) {
+    return this.#base.mkdir(this.#scope(path7), options);
   }
-  async rm(path6, options) {
-    await this.#base.rm(this.#scope(path6), options);
+  async rm(path7, options) {
+    await this.#base.rm(this.#scope(path7), options);
   }
   async cp(src, dest, options) {
     await this.#base.cp(this.#scope(src), this.#scope(dest), options);
@@ -4599,8 +4947,8 @@ var ScopedFs = class {
   async mv(src, dest) {
     await this.#base.mv(this.#scope(src), this.#scope(dest));
   }
-  async chmod(path6, mode) {
-    return this.#base.chmod(this.#scope(path6), mode);
+  async chmod(path7, mode) {
+    return this.#base.chmod(this.#scope(path7), mode);
   }
   async symlink(target, linkPath) {
     await this.#base.symlink(target, this.#scope(linkPath));
@@ -4608,35 +4956,35 @@ var ScopedFs = class {
   async link(existingPath, newPath) {
     await this.#base.link(this.#scope(existingPath), this.#scope(newPath));
   }
-  readFile(path6, options) {
-    return this.#base.readFile(this.#scope(path6), options);
+  readFile(path7, options) {
+    return this.#base.readFile(this.#scope(path7), options);
   }
-  readFileBuffer(path6) {
-    return this.#base.readFileBuffer(this.#scope(path6));
+  readFileBuffer(path7) {
+    return this.#base.readFileBuffer(this.#scope(path7));
   }
-  stat(path6) {
-    return this.#base.stat(this.#scope(path6));
+  stat(path7) {
+    return this.#base.stat(this.#scope(path7));
   }
-  lstat(path6) {
-    return this.#base.lstat(this.#scope(path6));
+  lstat(path7) {
+    return this.#base.lstat(this.#scope(path7));
   }
-  readdir(path6) {
-    return this.#base.readdir(this.#scope(path6));
+  readdir(path7) {
+    return this.#base.readdir(this.#scope(path7));
   }
-  readdirWithFileTypes(path6) {
-    return this.#base.readdirWithFileTypes(this.#scope(path6));
+  readdirWithFileTypes(path7) {
+    return this.#base.readdirWithFileTypes(this.#scope(path7));
   }
-  exists(path6) {
-    return this.#base.exists(this.#scope(path6));
+  exists(path7) {
+    return this.#base.exists(this.#scope(path7));
   }
-  readlink(path6) {
-    return this.#base.readlink(this.#scope(path6));
+  readlink(path7) {
+    return this.#base.readlink(this.#scope(path7));
   }
-  realpath(path6) {
-    return this.#base.realpath(this.#scope(path6)).then((p) => this.#unscope(p));
+  realpath(path7) {
+    return this.#base.realpath(this.#scope(path7)).then((p) => this.#unscope(p));
   }
-  utimes(path6, atime, mtime) {
-    return this.#base.utimes(this.#scope(path6), atime, mtime);
+  utimes(path7, atime, mtime) {
+    return this.#base.utimes(this.#scope(path7), atime, mtime);
   }
   resolvePath(base, relativePath) {
     return this.#base.resolvePath(base, relativePath);
@@ -4657,22 +5005,22 @@ var TrackedFs = class {
   getCreatedFiles() {
     return [...this.#createdFiles];
   }
-  async writeFile(path6, content, options) {
-    await this.#base.writeFile(path6, content, options);
-    this.#createdFiles.add(path6);
+  async writeFile(path7, content, options) {
+    await this.#base.writeFile(path7, content, options);
+    this.#createdFiles.add(path7);
   }
-  async appendFile(path6, content, options) {
-    await this.#base.appendFile(path6, content, options);
-    this.#createdFiles.add(path6);
+  async appendFile(path7, content, options) {
+    await this.#base.appendFile(path7, content, options);
+    this.#createdFiles.add(path7);
   }
-  async mkdir(path6, options) {
-    return this.#base.mkdir(path6, options);
+  async mkdir(path7, options) {
+    return this.#base.mkdir(path7, options);
   }
-  async rm(path6, options) {
-    await this.#base.rm(path6, options);
-    this.#createdFiles.delete(path6);
+  async rm(path7, options) {
+    await this.#base.rm(path7, options);
+    this.#createdFiles.delete(path7);
     if (options?.recursive) {
-      const prefix = path6.endsWith("/") ? path6 : path6 + "/";
+      const prefix = path7.endsWith("/") ? path7 : path7 + "/";
       for (const file of this.#createdFiles) {
         if (file.startsWith(prefix)) {
           this.#createdFiles.delete(file);
@@ -4689,8 +5037,8 @@ var TrackedFs = class {
     this.#createdFiles.delete(src);
     this.#createdFiles.add(dest);
   }
-  async chmod(path6, mode) {
-    return this.#base.chmod(path6, mode);
+  async chmod(path7, mode) {
+    return this.#base.chmod(path7, mode);
   }
   async symlink(target, linkPath) {
     await this.#base.symlink(target, linkPath);
@@ -4700,29 +5048,29 @@ var TrackedFs = class {
     await this.#base.link(existingPath, newPath);
     this.#createdFiles.add(newPath);
   }
-  readFile(path6, options) {
-    return this.#base.readFile(path6, options);
+  readFile(path7, options) {
+    return this.#base.readFile(path7, options);
   }
-  readFileBuffer(path6) {
-    return this.#base.readFileBuffer(path6);
+  readFileBuffer(path7) {
+    return this.#base.readFileBuffer(path7);
   }
-  stat(path6) {
-    return this.#base.stat(path6);
+  stat(path7) {
+    return this.#base.stat(path7);
   }
-  lstat(path6) {
-    return this.#base.lstat(path6);
+  lstat(path7) {
+    return this.#base.lstat(path7);
   }
-  readdir(path6) {
-    return this.#base.readdir(path6);
+  readdir(path7) {
+    return this.#base.readdir(path7);
   }
-  readdirWithFileTypes(path6) {
-    return this.#base.readdirWithFileTypes(path6);
+  readdirWithFileTypes(path7) {
+    return this.#base.readdirWithFileTypes(path7);
   }
-  exists(path6) {
-    return this.#base.exists(path6);
+  exists(path7) {
+    return this.#base.exists(path7);
   }
-  readlink(path6) {
-    return this.#base.readlink(path6);
+  readlink(path7) {
+    return this.#base.readlink(path7);
   }
   resolvePath(base, relativePath) {
     return this.#base.resolvePath(base, relativePath);
@@ -4730,11 +5078,11 @@ var TrackedFs = class {
   getAllPaths() {
     return this.#base.getAllPaths?.() ?? [];
   }
-  realpath(path6) {
-    return this.#base.realpath(path6);
+  realpath(path7) {
+    return this.#base.realpath(path7);
   }
-  utimes(path6, atime, mtime) {
-    return this.#base.utimes(path6, atime, mtime);
+  utimes(path7, atime, mtime) {
+    return this.#base.utimes(path7, atime, mtime);
   }
 };