@earendil-works/pi-durable 1.0.2 → 1.0.3

package/dist/env/node.js

@@ -1,15 +1,20 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants, createWriteStream } from "node:fs";
-import { access, appendFile, lstat, mkdir, mkdtemp, open as openFile, readdir, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { access, appendFile, lstat, mkdir, mkdtemp, opendir, open as openFile, readdir, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir, constants as osConstants, tmpdir } from "node:os";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { StreamDecoder } from "./decode.js";
 import { ExecutionError, err, FileError, ok, toError, } from "./index.js";
+import { LineScanner } from "./line-scan.js";
+import { NodeFileWatcher } from "./node-watch.js";
 const MAX_TIMEOUT_MS = 2_147_483_647;
 const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
 const EXIT_STDIO_GRACE_MS = 100;
 const SPILL_HIGH_WATER_MARK = 1024 * 1024;
+/** Largest single read of a `BinaryReader`, so a huge `length` allocates only as much as the file yields. */
+const BINARY_READ_CHUNK = 1024 * 1024;
 function resolveTimeoutMs(timeout) {
     if (timeout === undefined)
         return ok(undefined);
@@ -314,7 +319,7 @@ function waitForChildProcess(child, spillIsDraining) {
 class NodeTextLineReader {
     file;
     path;
-    decoder = new TextDecoder();
+    decoder = new StreamDecoder();
     chunk = new Uint8Array(64 * 1024);
     byteOffset = 0;
     buffered = "";
@@ -356,7 +361,7 @@ class NodeTextLineReader {
                     this.ended = true;
                 }
                 else {
-                    this.buffered += this.decoder.decode(this.chunk.subarray(0, bytesRead), { stream: true });
+                    this.buffered += this.decoder.decode(this.chunk.subarray(0, bytesRead));
                 }
             }
         }
@@ -377,17 +382,194 @@ class NodeTextLineReader {
         }
     }
 }
+function closedResult(what, path) {
+    return err(new FileError("invalid", `${what} is closed`, path));
+}
+class NodeBinaryReader {
+    file;
+    path;
+    closed = false;
+    constructor(file, path) {
+        this.file = file;
+        this.path = path;
+    }
+    async info(context) {
+        const aborted = abortResult(context.abortSignal, this.path);
+        if (aborted)
+            return aborted;
+        if (this.closed)
+            return closedResult("Binary reader", this.path);
+        try {
+            return fileInfoFromStats(this.path, await this.file.stat());
+        }
+        catch (error) {
+            return err(toFileError(error, this.path));
+        }
+    }
+    async read(offset, length, context) {
+        const aborted = abortResult(context.abortSignal, this.path);
+        if (aborted)
+            return aborted;
+        if (this.closed)
+            return closedResult("Binary reader", this.path);
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(length) || length < 0) {
+            return err(new FileError("invalid", "Offset and length must be non-negative safe integers", this.path));
+        }
+        const chunks = [];
+        let total = 0;
+        try {
+            while (total < length) {
+                const chunk = new Uint8Array(Math.min(length - total, BINARY_READ_CHUNK));
+                const { bytesRead } = await this.file.read(chunk, 0, chunk.length, offset + total);
+                const afterReadAbort = abortResult(context.abortSignal, this.path);
+                if (afterReadAbort)
+                    return afterReadAbort;
+                if (bytesRead === 0)
+                    break;
+                chunks.push(bytesRead === chunk.length ? chunk : chunk.subarray(0, bytesRead));
+                total += bytesRead;
+            }
+        }
+        catch (error) {
+            return err(toFileError(error, this.path));
+        }
+        if (chunks.length === 1)
+            return ok(chunks[0]);
+        const bytes = new Uint8Array(total);
+        let position = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, position);
+            position += chunk.length;
+        }
+        return ok(bytes);
+    }
+    async scanLines(options, context) {
+        const aborted = abortResult(context.abortSignal, this.path);
+        if (aborted)
+            return aborted;
+        if (this.closed)
+            return closedResult("Binary reader", this.path);
+        let scanner;
+        try {
+            scanner = new LineScanner(options.startLine, options.endLine);
+        }
+        catch {
+            return err(new FileError("invalid", "Invalid line range", this.path));
+        }
+        const chunk = new Uint8Array(64 * 1024);
+        try {
+            for (let position = 0;;) {
+                const { bytesRead } = await this.file.read(chunk, 0, chunk.length, position);
+                const afterReadAbort = abortResult(context.abortSignal, this.path);
+                if (afterReadAbort)
+                    return afterReadAbort;
+                if (bytesRead === 0)
+                    return ok(scanner.finish());
+                scanner.push(chunk.subarray(0, bytesRead));
+                position += bytesRead;
+            }
+        }
+        catch (error) {
+            return err(toFileError(error, this.path));
+        }
+    }
+    async close(_context) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.file.close().catch(() => undefined);
+    }
+}
+class NodeDirReader {
+    dir;
+    path;
+    done = false;
+    closed = false;
+    constructor(dir, path) {
+        this.dir = dir;
+        this.path = path;
+    }
+    async next(maxEntries, context) {
+        const aborted = abortResult(context.abortSignal, this.path);
+        if (aborted)
+            return aborted;
+        if (this.closed)
+            return closedResult("Directory reader", this.path);
+        if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0) {
+            return err(new FileError("invalid", "maxEntries must be a positive safe integer", this.path));
+        }
+        const entries = [];
+        try {
+            while (!this.done && entries.length < maxEntries) {
+                const entry = await this.dir.read();
+                if (entry === null) {
+                    this.done = true;
+                    break;
+                }
+                const loopAbort = abortResult(context.abortSignal, this.path);
+                if (loopAbort)
+                    return loopAbort;
+                const entryPath = resolve(this.path, entry.name);
+                let stats;
+                try {
+                    stats = await lstat(entryPath);
+                }
+                catch (error) {
+                    // Removed between enumeration and lstat: not part of the listing any more.
+                    if (isNodeError(error) && error.code === "ENOENT")
+                        continue;
+                    return err(toFileError(error, entryPath));
+                }
+                const info = fileInfoFromStats(entryPath, stats);
+                if (info.ok)
+                    entries.push(info.value);
+            }
+            return ok({ entries, done: this.done });
+        }
+        catch (error) {
+            return err(toFileError(error, this.path));
+        }
+    }
+    async close(_context) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.dir.close().catch(() => undefined);
+    }
+}
+function symlinkRefused(path, cause) {
+    return new FileError("invalid", "Refusing to follow a symbolic link", path, cause);
+}
 export class NodeExecutionEnv {
     /** Every local environment sees the same files. */
     id = "node:local";
     cwd;
     shellPath;
     shellEnv;
+    watchOptions;
     activeChildPids = new Set();
     constructor(options) {
         this.cwd = options.cwd;
         this.shellPath = options.shellPath;
         this.shellEnv = options.shellEnv;
+        this.watchOptions = options.watch ?? {};
+    }
+    async watch(targets, onChange, context) {
+        const aborted = abortResult(context.abortSignal);
+        if (aborted)
+            return aborted;
+        try {
+            const watcher = await NodeFileWatcher.open(targets, (path) => resolvePath(this.cwd, path), onChange, this.watchOptions);
+            const afterOpenAbort = abortResult(context.abortSignal);
+            if (afterOpenAbort) {
+                await watcher.close(context);
+                return afterOpenAbort;
+            }
+            return ok(watcher);
+        }
+        catch (error) {
+            return err(toFileError(error));
+        }
     }
     async absolutePath(path, _context) {
         return ok(resolvePath(this.cwd, path));
@@ -404,9 +586,26 @@ export class NodeExecutionEnv {
             return err(timeoutMsResult.error);
         const timeoutMs = timeoutMsResult.value;
         const cwd = options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd;
-        const shellConfig = await getShellConfig(this.shellPath);
-        if (!shellConfig.ok)
-            return shellConfig;
+        // A string runs through the shell; an argv array runs its program directly, without shell parsing.
+        let program;
+        let args;
+        let stdinCommand;
+        if (typeof command === "string") {
+            const shellConfig = await getShellConfig(this.shellPath);
+            if (!shellConfig.ok)
+                return shellConfig;
+            const commandFromStdin = shellConfig.value.commandTransport === "stdin";
+            program = shellConfig.value.shell;
+            args = commandFromStdin ? shellConfig.value.args : [...shellConfig.value.args, command];
+            stdinCommand = commandFromStdin ? command : undefined;
+        }
+        else {
+            const [first, ...rest] = command;
+            if (first === undefined)
+                return err(new ExecutionError("spawn_error", "Empty argv: no program to run"));
+            program = first;
+            args = rest;
+        }
         try {
             await access(cwd, constants.F_OK);
         }
@@ -439,14 +638,14 @@ export class NodeExecutionEnv {
                 onAbort();
             };
             // One decoder per stream, so a character split across chunks of one stream survives interleaving.
-            const stdoutDecoder = new TextDecoder();
-            const stderrDecoder = new TextDecoder();
+            const stdoutDecoder = new StreamDecoder();
+            const stderrDecoder = new StreamDecoder();
             // No output reaches the caller after exec() settled, for example from a descendant holding stdio open.
-            const emit = (text) => {
+            const emit = (text, stream) => {
                 if (settled || text === "" || options?.onOutput === undefined || callbackError !== undefined)
                     return;
                 try {
-                    options.onOutput(text, context);
+                    options.onOutput(text, context, { stream });
                 }
                 catch (error) {
                     failCallback(error);
@@ -532,19 +731,18 @@ export class NodeExecutionEnv {
                 });
             };
             try {
-                const commandFromStdin = shellConfig.value.commandTransport === "stdin";
-                child = spawn(shellConfig.value.shell, commandFromStdin ? shellConfig.value.args : [...shellConfig.value.args, command], {
+                child = spawn(program, args, {
                     cwd,
                     detached: process.platform !== "win32",
                     env: getShellEnv(this.shellEnv, options?.env, options?.inheritEnv),
-                    stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
+                    stdio: [stdinCommand === undefined ? "ignore" : "pipe", "pipe", "pipe"],
                     windowsHide: true,
                 });
                 if (child.pid)
                     this.activeChildPids.add(child.pid);
-                if (commandFromStdin) {
+                if (stdinCommand !== undefined) {
                     child.stdin?.on("error", () => { });
-                    child.stdin?.end(command);
+                    child.stdin?.end(stdinCommand);
                 }
             }
             catch (error) {
@@ -565,8 +763,8 @@ export class NodeExecutionEnv {
                 else
                     signal.addEventListener("abort", onAbort, { once: true });
             }
-            const feed = (decoder) => (chunk) => {
-                emit(decoder.decode(chunk, { stream: true }));
+            const feed = (source, decoder) => (chunk) => {
+                emit(decoder.decode(chunk), source);
                 const spill = options?.spill;
                 if (spill === undefined || chunk.length === 0)
                     return;
@@ -587,14 +785,14 @@ export class NodeExecutionEnv {
                 spillPrefix.length = 0;
                 startSpill(chunk);
             };
-            child.stdout?.on("data", feed(stdoutDecoder));
-            child.stderr?.on("data", feed(stderrDecoder));
+            child.stdout?.on("data", feed("stdout", stdoutDecoder));
+            child.stderr?.on("data", feed("stderr", stderrDecoder));
             void waitForChildProcess(child, () => spillError === undefined &&
                 spillStart !== undefined &&
                 (spillStream === undefined || spillBackpressured)).then(async ({ code, signal: exitSignal }) => {
                 await finishSpill();
-                emit(stdoutDecoder.decode());
-                emit(stderrDecoder.decode());
+                emit(stdoutDecoder.decode(), "stdout");
+                emit(stderrDecoder.decode(), "stderr");
                 if (callbackError) {
                     settle(err(callbackError));
                     return;
@@ -688,6 +886,50 @@ export class NodeExecutionEnv {
             return err(toFileError(error, resolved));
         }
     }
+    async openBinaryReader(path, options, context) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(context.abortSignal, resolved);
+        if (aborted)
+            return aborted;
+        const noFollow = options?.noFollow === true;
+        let file;
+        try {
+            let flags = constants.O_RDONLY;
+            if (process.platform === "win32") {
+                // Windows has no O_NOFOLLOW; check the final component before opening (not race-free).
+                if (noFollow && (await lstat(resolved)).isSymbolicLink())
+                    return err(symlinkRefused(resolved));
+            }
+            else {
+                // Nonblocking, so opening a FIFO does not wait for a writer.
+                flags |= constants.O_NONBLOCK;
+                if (noFollow)
+                    flags |= constants.O_NOFOLLOW;
+            }
+            file = await openFile(resolved, flags);
+            const stats = await file.stat();
+            if (!stats.isFile()) {
+                await file.close().catch(() => undefined);
+                return err(stats.isDirectory()
+                    ? new FileError("is_directory", "EISDIR: illegal operation on a directory, read", resolved)
+                    : new FileError("invalid", "Not a regular file", resolved));
+            }
+            const afterOpenAbort = abortResult(context.abortSignal, resolved);
+            if (afterOpenAbort) {
+                await file.close().catch(() => undefined);
+                return afterOpenAbort;
+            }
+            return ok(new NodeBinaryReader(file, resolved));
+        }
+        catch (error) {
+            await file?.close().catch(() => undefined);
+            // O_NOFOLLOW reports a final-component symlink as ELOOP (EMLINK on some BSDs).
+            if (noFollow && isNodeError(error) && (error.code === "ELOOP" || error.code === "EMLINK")) {
+                return err(symlinkRefused(resolved, toError(error)));
+            }
+            return err(toFileError(error, resolved));
+        }
+    }
     async writeFile(path, content, context) {
         const resolved = resolvePath(this.cwd, path);
         const signal = context.abortSignal;
@@ -757,6 +999,9 @@ export class NodeExecutionEnv {
         let file;
         try {
             file = await openFile(resolved, "r+");
+            // POSIX refuses to open a directory for writing; Windows opens it, so check explicitly.
+            if ((await file.stat()).isDirectory())
+                return err(new FileError("is_directory", "Is a directory", resolved));
             await file.sync();
             const afterSyncAbort = abortResult(signal, resolved);
             return afterSyncAbort ?? ok(undefined);
@@ -823,6 +1068,24 @@ export class NodeExecutionEnv {
             return err(toFileError(error, resolved));
         }
     }
+    async openDirReader(path, context) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(context.abortSignal, resolved);
+        if (aborted)
+            return aborted;
+        try {
+            const dir = await opendir(resolved);
+            const afterOpenAbort = abortResult(context.abortSignal, resolved);
+            if (afterOpenAbort) {
+                await dir.close().catch(() => undefined);
+                return afterOpenAbort;
+            }
+            return ok(new NodeDirReader(dir, resolved));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
     async canonicalPath(path, context) {
         const resolved = resolvePath(this.cwd, path);
         const aborted = abortResult(context.abortSignal, resolved);