@poe-platform/safe-bash 0.1.824 → 0.1.825

package/dist/safe-bash-sqlite-engine/storage.d.ts

@@ -9,3 +9,5 @@ export { readSqliteRecord } from './sqlite-record-read.js';
 export type { SqliteEditSnapshot } from './sqlite-edit-snapshot.js';
 export type { SqliteFinalizer } from './sqlite-finalization.js';
 export { withSqliteReadSession } from './sqlite-read-session.js';
+export { withSqliteQueryRecords } from './sqlite-query-records.js';
+export { prepareSqliteAttachments } from './sqlite-attachments.js';

package/dist/safe-bash-sqlite-engine/storage.js

@@ -2,7 +2,7 @@ import {
   createSqliteVfs,
   readSqliteFile,
   writeSqliteFile
-} from "../safe-bash/command-chunks/chunk-3UDJYSAF.js";
+} from "../safe-bash/command-chunks/chunk-IX3B4HCD.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 
 // packages/safe-bash-sqlite-engine/src/sqlite-transaction.ts
@@ -21,7 +21,7 @@ function verifySqliteSnapshot(actual, expected) {
 }
 
 // packages/safe-bash-sqlite-engine/src/sqlite-sources.ts
-async function acquireSqliteSources(fs, path, signal) {
+async function acquireSqliteSources(fs, path, signal, options = {}) {
   signal.throwIfAborted();
   const resolutions = [];
   const handles = [];
@@ -39,17 +39,18 @@ async function acquireSqliteSources(fs, path, signal) {
     signal.throwIfAborted();
     return true;
   };
-  const resolve = async (sourcePath) => {
-    const capabilities = await fs.capabilitiesFor?.(sourcePath, { signal, stagingResolution: true }) ?? fs.capabilities;
-    if (capabilities.synchronousStagingResolution !== true || capabilities.retainedRead !== true || !fs.prepareStagingResolution || !fs.openReadFile) {
+  const resolve = async (sourcePath, followFinalSymlink = false) => {
+    const capabilities = await fs.capabilitiesFor?.(sourcePath, { signal, stagingResolution: true, followFinalSymlink }) ?? fs.capabilities;
+    if (capabilities.synchronousStagingResolution !== true || followFinalSymlink && capabilities.synchronousFollowedStagingResolution !== true || capabilities.retainedRead !== true || !fs.prepareStagingResolution || !fs.openReadFile) {
       throw new FsError2("ENOTSUP", { path: sourcePath, message: "SQLite source acquisition requires retained reads and synchronous binding guards" });
     }
-    const resolution = await fs.prepareStagingResolution(sourcePath, { signal });
+    const resolution = await fs.prepareStagingResolution(sourcePath, { signal, followFinalSymlink });
     resolutions.push(resolution);
     return resolution;
   };
   try {
-    const database = await resolve(path);
+    const follow = options.followFinalSymlink === true && (await fs.lstat(path, { signal })).type === "symlink";
+    const database = await resolve(path, follow);
     for (const suffix of ["wal", "journal", "shm"]) await resolve(`${database.path}-${suffix}`);
     validate();
     const sources = [];
@@ -66,9 +67,9 @@ async function acquireSqliteSources(fs, path, signal) {
       validate();
       const controls = (operationSignal) => ({ signal: operationSignal ? AbortSignal.any([signal, operationSignal]) : signal });
       const file = {
-        async stat(options) {
+        async stat(options2) {
           validate();
-          const operation = controls(options?.signal);
+          const operation = controls(options2?.signal);
           operation.signal.throwIfAborted();
           const stat = await handle.stat(operation);
           operation.signal.throwIfAborted();
@@ -76,11 +77,11 @@ async function acquireSqliteSources(fs, path, signal) {
           validate();
           return stat;
         },
-        async read(position, maxBytes, options) {
+        async read(position, maxBytes, options2) {
           validate();
           if (!Number.isSafeInteger(position) || position < 0 || !Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new RangeError("Invalid SQLite source read");
           const count = Math.min(maxBytes, 16384);
-          const operation = controls(options?.signal);
+          const operation = controls(options2?.signal);
           operation.signal.throwIfAborted();
           const bytes = await handle.read(position, count, operation);
           operation.signal.throwIfAborted();
@@ -379,7 +380,7 @@ async function withPrivateSqliteSession(options, operation) {
     const { createSqliteRuntime, FacadeVFS } = await import("./index.js");
     const runtime = await createSqliteRuntime({ signal });
     const vfs = "sqlite-private";
-    const mxPathname = Math.max(4096, new TextEncoder().encode(path).length + 256);
+    const mxPathname = Math.max(4096, new TextEncoder().encode(path).length + 256, ...(options.filenames ?? []).map((file) => new TextEncoder().encode(file.name).length + 256));
     const code = runtime.module.vfs_register(Object.assign(new FacadeVFS(vfs, runtime.module), callbacks, { mxPathname }), true);
     if (code !== 0) throw new FsError5("EIO", { message: `SQLite VFS registration failed (${code})` });
     value = await withSqliteDatabase(runtime.module, { path, vfs, signal, check: callbacks.throwIfFailed }, (connection) => operation({ ...runtime, ...connection, check: callbacks.throwIfFailed }));
@@ -1258,9 +1259,20 @@ async function withSqliteStatement(module, options, operation) {
   const bindText = module.cwrap("sqlite3_bind_text", "number", ["number", "number", "number", "number", "number"]);
   const result = (code) => {
     check();
-    if (code !== 0) throw new FsError15("EIO", { message: `Native SQLite statement failed (${code})` });
+    if (code === 0) return;
+    let message = `Native SQLite statement failed (${code})`;
+    if (options.single) {
+      const errorMessage = module.cwrap("sqlite3_errmsg", "number", ["number"]);
+      const pointer = errorMessage(database);
+      let end = pointer;
+      if (pointer > 0 && pointer < module.HEAPU8.length) {
+        while (end < module.HEAPU8.length && end - pointer < 65536 && module.HEAPU8[end]) end++;
+        if (end < module.HEAPU8.length && module.HEAPU8[end] === 0) message = decoder.decode(module.HEAPU8.subarray(pointer, end));
+      }
+    }
+    throw new FsError15("EIO", { message });
   };
-  let out = 0, statement = 0, accepting = true, current, value;
+  let out = 0, sqlPointer = 0, statement = 0, accepting = true, current, value;
   const errors = [];
   const resetCursor = async (failed, failure) => {
     try {
@@ -1358,16 +1370,126 @@ async function withSqliteStatement(module, options, operation) {
     const iterator = iterate();
     return iterator;
   };
+  const records = () => {
+    async function* iterate() {
+      if (!accepting) throw new FsError15("EBADF", { message: "SQLite statement is closed" });
+      if (current) throw new FsError15("EBUSY", { message: "SQLite cursor is already active" });
+      current = iterator;
+      let failed = false, failure;
+      try {
+        const readonly = module.cwrap("sqlite3_stmt_readonly", "number", ["number"]);
+        if (!readonly(statement) || parameters(statement)) throw new TypeError("Expected an unbound read-only SQLite query");
+        const size = count(statement);
+        if (size > 2e3) throw new RangeError("SQLite record exceeds column budget");
+        while (true) {
+          await yieldTurn4(signal);
+          check();
+          const code = await step(statement);
+          check();
+          signal.throwIfAborted();
+          if (code === 101) return;
+          if (code !== 100) {
+            result(code);
+            return;
+          }
+          let active = true;
+          try {
+            const values = [];
+            for (let column = 0; column < size; column++) {
+              const kind = type(statement, column);
+              if (kind === 5) {
+                values.push(null);
+                continue;
+              }
+              if (kind === 2) {
+                values.push(real(statement, column));
+                continue;
+              }
+              const pointer = kind === 4 ? blob(statement, column) : text(statement, column);
+              const bytes = length(statement, column);
+              if (bytes < 0 || bytes && (!pointer || pointer + bytes > module.HEAPU8.length)) throw new RangeError("Invalid SQLite field address");
+              if (kind === 1) {
+                if (bytes > 20) throw new RangeError("Invalid SQLite integer");
+                values.push(BigInt(decoder.decode(module.HEAPU8.subarray(pointer, pointer + bytes))));
+                continue;
+              }
+              if (kind !== 3 && kind !== 4) throw new TypeError("Unexpected SQLite field type");
+              values.push({ type: kind === 3 ? "text" : "blob", size: bytes, bytes: { async *[Symbol.asyncIterator]() {
+                const ready = () => {
+                  signal.throwIfAborted();
+                  check();
+                  if (!active || !accepting) throw new FsError15("EBADF", { message: "SQLite row lease is closed" });
+                };
+                ready();
+                for (let offset = 0; offset < bytes; offset += 16384) {
+                  await yieldTurn4(signal);
+                  ready();
+                  yield module.HEAPU8.slice(pointer + offset, pointer + Math.min(offset + 16384, bytes));
+                }
+              } } });
+            }
+            yield values;
+          } finally {
+            active = false;
+          }
+        }
+      } catch (error) {
+        failed = true;
+        failure = error;
+        throw error;
+      } finally {
+        await resetCursor(failed, failure);
+      }
+    }
+    const iterator = iterate();
+    return iterator;
+  };
   try {
-    out = module._malloc(4);
+    out = module._malloc(options.single ? 8 : 4);
     if (!out) throw new RangeError("SQLite memory allocation failed");
     new DataView(module.HEAPU8.buffer).setInt32(out, 0, true);
-    const code = await prepare(database, sql, -1, out, 0);
-    statement = new DataView(module.HEAPU8.buffer).getInt32(out, true);
+    let code;
+    if (options.single) {
+      const bytes = encoder.encode(sql);
+      sqlPointer = module._malloc(bytes.length + 1);
+      if (!sqlPointer) throw new RangeError("SQLite memory allocation failed");
+      module.HEAPU8.set(bytes, sqlPointer);
+      module.HEAPU8[sqlPointer + bytes.length] = 0;
+      new DataView(module.HEAPU8.buffer).setInt32(out + 4, 0, true);
+      const ownedPrepare = module.cwrap("sqlite3_prepare_v2", "number", ["number", "number", "number", "number", "number"], { async: true });
+      code = await ownedPrepare(database, sqlPointer, bytes.length + 1, out, out + 4);
+      statement = new DataView(module.HEAPU8.buffer).getInt32(out, true);
+      result(code);
+      const tail = new DataView(module.HEAPU8.buffer).getInt32(out + 4, true);
+      if (tail < sqlPointer || tail > sqlPointer + bytes.length) throw new RangeError("Invalid SQLite statement tail");
+      for (let position = tail; position < sqlPointer + bytes.length; position++) if (![9, 10, 11, 12, 13, 32].includes(module.HEAPU8[position])) throw new TypeError("Expected a single SQLite statement");
+    } else {
+      code = await prepare(database, sql, -1, out, 0);
+      statement = new DataView(module.HEAPU8.buffer).getInt32(out, true);
+    }
     result(code);
     signal.throwIfAborted();
     if (!statement) throw new FsError15("EIO", { message: "SQLite returned an empty statement" });
-    value = await operation({ rows });
+    value = await operation({ rows, records, columns() {
+      if (!accepting) throw new FsError15("EBADF", { message: "SQLite statement is closed" });
+      signal.throwIfAborted();
+      check();
+      const names = [], size = count(statement);
+      const name = module.cwrap("sqlite3_column_name", "number", ["number", "number"]);
+      let budget = 65536;
+      for (let index = 0; index < size; index++) {
+        const pointer = name(statement, index);
+        let end = pointer;
+        if (pointer <= 0 || pointer >= module.HEAPU8.length) throw new RangeError("Invalid SQLite column name");
+        while (end < module.HEAPU8.length && module.HEAPU8[end]) {
+          if (--budget < 0) throw new RangeError("SQLite column names exceed byte budget");
+          end++;
+        }
+        if (end === module.HEAPU8.length) throw new RangeError("Invalid SQLite column name");
+        names.push(decoder.decode(module.HEAPU8.subarray(pointer, end)));
+      }
+      return names;
+    } });
   } catch (error) {
     errors.push(error);
   }
@@ -1384,6 +1506,11 @@ async function withSqliteStatement(module, options, operation) {
   } catch (error) {
     if (!errors.includes(error)) errors.push(error);
   }
+  if (sqlPointer) try {
+    module._free(sqlPointer);
+  } catch (error) {
+    errors.push(error);
+  }
   if (out) try {
     module._free(out);
   } catch (error) {
@@ -1677,9 +1804,9 @@ async function readSqliteRecord(record, options) {
   return values;
 }
 
-// packages/safe-bash-sqlite-engine/src/sqlite-read-session.ts
+// packages/safe-bash-sqlite-engine/src/sqlite-input-snapshots.ts
 import { FsError as FsError19 } from "../safe-bash-contracts/index.js";
-async function withSqliteReadSession(options, operation) {
+async function withSqliteInputSnapshots(options, operation) {
   const { fs, signal } = options;
   for (const limit of [options.maxFileBytes, options.maxIndexBytes, options.maxOpenFiles]) if (!Number.isSafeInteger(limit) || limit < 0) throw new RangeError("Invalid SQLite snapshot budget");
   const inputs = [{ path: options.path, alias: "main" }, ...(options.attachments ?? []).map((input) => ({ ...input }))];
@@ -1689,24 +1816,16 @@ async function withSqliteReadSession(options, operation) {
   let value;
   try {
     for (const [index, input] of inputs.entries()) {
-      const sources = await acquireSqliteSources(fs, input.path, signal);
+      const sources = await acquireSqliteSources(fs, input.path, signal, { followFinalSymlink: true });
       try {
         if (!sources.database) throw new FsError19("ENOENT", { path: input.path });
         await copySqliteSnapshot({ ...options, sources, storage, path: `${storage.directory}/database-${index}` });
+        input.path = sources.path;
       } finally {
         await sources.close();
       }
     }
-    value = await withPrivateSqliteSession({ ...options, fs: storage.fs, directory: storage.directory, path: storage.directory + "/database-0" }, async (session) => {
-      for (let index = 1; index < inputs.length; index++) {
-        const alias = inputs[index].alias;
-        await withSqliteStatement(session.module, { ...session, signal, sql: 'ATTACH DATABASE ? AS "' + alias.replaceAll('"', '""') + '"' }, async (statement) => {
-          for await (const ignored of statement.rows([`${storage.directory}/database-${index}`], [])) signal.throwIfAborted();
-        });
-      }
-      await session.execute("PRAGMA query_only=ON");
-      return operation(session);
-    });
+    value = await operation(storage, inputs);
   } catch (error) {
     errors.push(error);
   }
@@ -1719,13 +1838,187 @@ async function withSqliteReadSession(options, operation) {
   if (errors.length) throw new AggregateError(errors, "SQLite read session and cleanup failed");
   return value;
 }
+
+// packages/safe-bash-sqlite-engine/src/sqlite-read-session.ts
+async function withSqliteReadSession(options, operation) {
+  const { signal } = options;
+  return withSqliteInputSnapshots(options, async (storage, inputs) => {
+    return withPrivateSqliteSession({ ...options, fs: storage.fs, directory: storage.directory, path: storage.directory + "/database-0", filenames: inputs.map((input, index) => ({ path: storage.directory + "/database-" + index, name: input.path })) }, async (session) => {
+      await session.execute("PRAGMA query_only=ON");
+      for (let index = 1; index < inputs.length; index++) {
+        const alias = inputs[index].alias;
+        await withSqliteStatement(session.module, { ...session, signal, sql: 'ATTACH DATABASE ? AS "' + alias.replaceAll('"', '""') + '"' }, async (statement) => {
+          for await (const ignored of statement.rows([`${storage.directory}/database-${index}`], [])) signal.throwIfAborted();
+        });
+      }
+      return operation(session);
+    });
+  });
+}
+
+// packages/safe-bash-sqlite-engine/src/sqlite-query-records.ts
+import { yieldTurn as yieldTurn8 } from "../safe-bash-contracts/yield.js";
+import { FsError as FsError20 } from "../safe-bash-contracts/index.js";
+async function withSqliteQueryRecords(options, operation) {
+  const { signal } = options;
+  return withSqliteInputSnapshots(options, async (storage, inputs) => {
+    const file = await storage.fs.open(storage.directory + "/results", { access: "readwrite", creation: "exclusive", signal });
+    let accepting = true, size = 0, iterator, value;
+    const errors = [];
+    const check = () => {
+      signal.throwIfAborted();
+      if (!accepting) throw new FsError20("EBADF", { message: "SQLite query results are closed" });
+    };
+    try {
+      let columns = [];
+      await withPrivateSqliteSession({ ...options, fs: storage.fs, directory: storage.directory, path: storage.directory + "/database-0", filenames: inputs.map((input, index) => ({ path: storage.directory + "/database-" + index, name: input.path })) }, async (session) => {
+        await session.execute("PRAGMA query_only=ON");
+        for (let index = 1; index < inputs.length; index++) await withSqliteStatement(session.module, { ...session, signal, sql: 'ATTACH DATABASE ? AS "' + inputs[index].alias.replaceAll('"', '""') + '"' }, async (statement) => {
+          for await (const ignored of statement.rows([storage.directory + "/database-" + index], [])) signal.throwIfAborted();
+        });
+        let progressFailure;
+        session.module.progress_handler(session.database, 1e3, async () => {
+          try {
+            await yieldTurn8(signal);
+            return 0;
+          } catch (error) {
+            progressFailure = error;
+            return 1;
+          }
+        }, 0);
+        try {
+          columns = await withSqliteStatement(session.module, { ...session, signal, single: true, sql: options.sql }, async (statement) => statement.columns());
+          await withSqliteStatement(session.module, { ...session, signal, single: true, sql: "SELECT * FROM (" + options.sql + ")" }, async (statement) => {
+            for await (const row of statement.records()) {
+              const record = sqliteRecord(row), end = size + 8 + record.size;
+              if (!Number.isSafeInteger(end) || end > options.maxFileBytes) throw new FsError20("EFBIG", { message: "SQLite query results exceed file budget" });
+              const header = new Uint8Array(8);
+              new DataView(header.buffer).setBigUint64(0, BigInt(record.size));
+              await writeSqliteFile(file, header, size, signal);
+              size += 8;
+              for await (const bytes of record.bytes(signal)) {
+                await writeSqliteFile(file, bytes, size, signal);
+                size += bytes.length;
+              }
+              if (size !== end) throw new FsError20("EIO", { message: "Invalid SQLite query record size" });
+            }
+          });
+        } catch (error) {
+          if (progressFailure !== void 0) throw progressFailure;
+          throw error;
+        } finally {
+          session.module.progress_handler(session.database, 0, null, 0);
+        }
+      });
+      const snapshot = await file.stat({ signal });
+      verifySqliteSnapshot(snapshot, snapshot);
+      const read = async (bytes, position) => {
+        check();
+        verifySqliteSnapshot(await file.stat({ signal }), snapshot);
+        const complete = await readSqliteFile(file, bytes, position, signal);
+        check();
+        verifySqliteSnapshot(await file.stat({ signal }), snapshot);
+        if (!complete) throw new FsError20("EIO", { message: "Truncated SQLite query record" });
+      };
+      const rows = async function* () {
+        for (let position = 0; position < size; ) {
+          check();
+          const header = new Uint8Array(8);
+          await read(header, position);
+          const length = Number(new DataView(header.buffer).getBigUint64(0)), start = position + 8;
+          if (!Number.isSafeInteger(length) || length < 1 || length > size - start) throw new FsError20("EIO", { message: "Invalid SQLite query record size" });
+          yield await readSqliteRecord({ size: length, bytes(offset = 0, count = length - offset) {
+            return { async *[Symbol.asyncIterator]() {
+              check();
+              if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(count) || offset < 0 || count < 0 || offset + count > length) throw new RangeError("Invalid SQLite query record range");
+              for (let done = 0; done < count; ) {
+                check();
+                const bytes = new Uint8Array(Math.min(16384, count - done));
+                await read(bytes, start + offset + done);
+                check();
+                done += bytes.length;
+                yield bytes;
+              }
+            } };
+          } }, { signal, maxColumns: 2e3 });
+          position = start + length;
+        }
+      };
+      iterator = rows();
+      value = await operation({ [Symbol.asyncIterator]: () => iterator }, columns);
+    } catch (error) {
+      errors.push(error);
+    }
+    accepting = false;
+    try {
+      await iterator?.return(void 0);
+    } catch (error) {
+      if (!errors.includes(error)) errors.push(error);
+    }
+    try {
+      await file.close();
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length) throw new AggregateError(errors, "SQLite query result cleanup failed");
+    return value;
+  });
+}
+
+// packages/safe-bash-sqlite-engine/src/sqlite-attachments.ts
+import { FsError as FsError21 } from "../safe-bash-contracts/index.js";
+async function prepareSqliteAttachments(options) {
+  const { fs, signal } = options, attachments = options.attachments?.map((input) => ({ ...input })) ?? [];
+  if (!attachments.length) return;
+  if (!fs.open) throw new FsError21("ENOSYS", { message: "SQLite attachments require descriptor storage" });
+  const ensure = async (path) => {
+    try {
+      await fs.stat(path, { signal });
+      return;
+    } catch (error) {
+      if (!(error instanceof FsError21) || error.code !== "ENOENT") throw error;
+    }
+    const file = await fs.open(path, { access: "readwrite", creation: "ifMissing", signal });
+    await file.close();
+  };
+  await ensure(options.path);
+  await withSqliteInputSnapshots({ ...options, attachments: [] }, async (storage) => {
+    await withPrivateSqliteSession({ ...options, fs: storage.fs, directory: storage.directory, path: storage.directory + "/database-0" }, async (session) => {
+      const execute = async (sql, bindings = []) => withSqliteStatement(session.module, { ...session, signal, sql, single: true }, async (statement) => {
+        for await (const ignored of statement.rows(bindings, [])) signal.throwIfAborted();
+      });
+      for (const [index, input] of attachments.entries()) {
+        await execute("ATTACH DATABASE ? AS [" + input.alias + "]", [":memory:"]);
+        try {
+          await ensure(input.path);
+        } catch (error) {
+          signal.throwIfAborted();
+          if (error instanceof FsError21 && ["ENOENT", "ENOTDIR", "EACCES", "EISDIR"].includes(error.code)) throw new FsError21("EIO", { message: "unable to open database: " + input.path });
+          throw error;
+        }
+        const sources = await acquireSqliteSources(fs, input.path, signal, { followFinalSymlink: true });
+        const path = storage.directory + "/database-" + (index + 1);
+        try {
+          await copySqliteSnapshot({ ...options, sources, storage, path });
+        } finally {
+          await sources.close();
+        }
+        await execute("DETACH DATABASE [" + input.alias + "]");
+        await execute("ATTACH DATABASE ? AS [" + input.alias + "]", [path]);
+      }
+    });
+  });
+}
 export {
   createPrivateSqliteStorage,
+  prepareSqliteAttachments,
   readSqliteBlob,
   readSqliteRecord,
   sqliteRecord,
   transactSqlite,
   withPrivateSqliteSession,
+  withSqliteQueryRecords,
   withSqliteReadSession,
   withSqliteStatement,
   writeSqliteBlob

package/dist/safe-bash-sqlite-engine/types.d.ts

@@ -5,6 +5,7 @@ export interface NativeSqliteModule {
     cwrap(name: string, result: string, arguments_: string[], options?: {
         async: boolean;
     }): unknown;
+    progress_handler(database: number, operations: number, callback: (() => number | Promise<number>) | null, context: number): void;
     vfs_register(vfs: object, makeDefault: boolean): number;
 }
 export interface SqliteRuntime {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-bash",
-  "version": "0.1.824",
+  "version": "0.1.825",
   "description": "Extensible virtual shell with pluggable filesystems and streaming commands",
   "type": "module",
   "license": "MIT",
@@ -1415,7 +1415,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@poe-platform/safe-fs": "0.1.824",
+    "@poe-platform/safe-fs": "0.1.825",
     "pdf-lib": "1.17.1",
     "@types/node": "^25.2.2",
     "@formatjs/intl-numberformat": "9.4.0",