@gjsify/fs 0.30.0 → 0.32.0

package/lib/types/fd-io.d.ts

@@ -0,0 +1,188 @@
+import Gio from '@girs/gio-2.0';
+import type { OpenSpec } from './posix-flags.js';
+/** Build a Node `ErrnoException` from a code we determined ourselves. */
+export declare function fsError(code: string, syscall: string, path?: string, dest?: string): NodeJS.ErrnoException;
+/**
+ * Can this host name an open descriptor as a path?
+ *
+ * Measured once, and only ONCE it is needed — a module-eval probe would run in
+ * every consumer that merely imports `node:fs`. `respond-with-file.ts` carries
+ * the scar of assuming procfs exists: the path resolved to nothing on macOS,
+ * `statSync` threw, and a swallowed catch meant the check silently never ran.
+ */
+export declare function hasProcFd(): boolean;
+/**
+ * A path that names the DESCRIPTOR rather than the name it was opened from,
+ * or `null` where the host cannot express one.
+ *
+ * This is what makes `fstat`/`fchmod`/`ftruncate` survive a rename or an
+ * unlink: `/proc/self/fd/<fd>` resolves to the inode the fd holds, even after
+ * the directory entry is gone.
+ */
+export declare function fdPath(fd: number): string | null;
+/**
+ * `open(2)`.
+ *
+ * The mode reaches the kernel, so it is applied ATOMICALLY at creation, masked
+ * by the live umask, and it survives a crash — none of which a post-create or
+ * close-time `chmod` can offer. `O_EXCL` is likewise the kernel's, so it is
+ * atomic and it refuses a symlink whatever the link points at.
+ */
+export declare function openFd(path: string, spec: OpenSpec, mode: number): number;
+export declare function closeFd(fd: number): void;
+/**
+ * Name the reason `open(2)` refused.
+ *
+ * GJS cannot read `errno`, so the code is reconstructed from what is observable
+ * AFTER the kernel has already refused. That makes this a classification, not a
+ * check-then-act: it never decides whether to create anything, so it carries no
+ * TOCTOU. The `lstat`-equivalent lookup (`NOFOLLOW_SYMLINKS`) matters — a
+ * dangling symlink must read as "the name is taken", which is exactly why
+ * `file_test(EXISTS)` was the wrong instrument for the check this replaces.
+ */
+export declare function classifyOpenFailure(path: string, spec: OpenSpec): NodeJS.ErrnoException;
+/**
+ * Does this `GFileInfo` actually ANSWER, or is it an empty shell?
+ *
+ * `g_file_query_info()` does NOT fail when the kernel refuses to stat a name.
+ * A path under a directory the process cannot search comes back as a non-NULL
+ * `GFileInfo` carrying NO attributes at all — measured directly:
+ * `list_attributes(null)` is `[]` and `has_attribute('standard::type')` is
+ * `false`, where an ordinary lookup returns `['standard::type']`.
+ *
+ * Two things follow, and this package got both wrong. Reading the type off
+ * that shell logs `GFileInfo created without standard::type` plus
+ * `g_file_info_get_file_type: should not be reached` — two `GLib-GIO-CRITICAL`
+ * lines that `G_DEBUG=fatal-criticals` (standard in GNOME CI, and the exact
+ * condition {@link isSeekableFd} below exists to satisfy) turns into a
+ * SIGABRT before the caller's `catch` can run. And taking the shell as proof
+ * the name EXISTS answered EEXIST — "the name is taken" — for a plain
+ * permission denial, which sends an `openSync(lock,'wx')` retry loop round
+ * forever and makes the ubiquitous
+ * `try { mkdirSync(d) } catch (e) { if (e.code !== 'EEXIST') throw }`
+ * swallow a hard EACCES and carry on as if the directory were there.
+ *
+ * So every read of an attribute in this module is gated on this, and a
+ * `false` means "no answer" — never "no".
+ *
+ * Exported because the stat family needs the identical gate and used to lack
+ * it: `statSync` under an unsearchable directory built a `Stats` from the empty
+ * shell, which is BOTH of the failures above at once — four CRITICALs (hence a
+ * SIGABRT under `G_DEBUG=fatal-criticals`) and then a fabricated `{mode: 0,
+ * size: 0, ino: 0}` returned as fact where Node raises EACCES. See
+ * `statsFrom()` in `stats.ts`, which is the one place that decision now lives.
+ */
+export declare function answered(info: Gio.FileInfo | null): boolean;
+/** The same reconstruction for `mkdir(2)`, which also returns a bare `-1`. */
+export declare function classifyMkdirFailure(path: string): NodeJS.ErrnoException;
+/**
+ * Can this descriptor be positioned at all?
+ *
+ * `seekFd` used to be issued before EVERY read and write, unconditionally, so a
+ * FIFO / pipe / socket / tty produced one
+ * `g_io_channel_seek_position: assertion 'channel->is_seekable' failed`
+ * per I/O call — a `GLib-CRITICAL`, which `G_DEBUG=fatal-criticals` (standard
+ * in GNOME CI) turns into an abort. The bytes happened to survive because a
+ * pipe ignores the offset, so the failed seek was a silent no-op and `_pos`
+ * accumulated a number that meant nothing.
+ *
+ * The answer is therefore ASKED FOR rather than discovered by tripping an
+ * assertion. `GIOChannel` decides it with `lseek(fd, 0, SEEK_CUR)`, which GJS
+ * cannot reach, and its `is_seekable` field is not introspectable — so the file
+ * TYPE is the available instrument.
+ *
+ * The rule is deliberately narrow: only `S_IFIFO` and `S_IFSOCK` are refused.
+ * The tempting "seekable means `S_IFREG` or `S_IFBLK`" is WRONG and would trade
+ * this defect for a worse one — a character device usually seeks fine
+ * (`noop_llseek`), and Node performs positional I/O on `/dev/null`,
+ * `/dev/zero` and `/dev/urandom` without complaint (measured against
+ * v24.15.0). Refusing those would have turned a stray log line into an ESPIPE
+ * that Node never raises.
+ *
+ * The type test alone is NOT the whole answer, and a TTY is where it runs out:
+ * `/dev/pts/N` is `S_IFCHR` exactly like `/dev/zero`, but it has `no_llseek`.
+ * So after the type test the DESCRIPTOR ITSELF is asked, with the same
+ * `lseek(fd, 0, SEEK_CUR)` `GIOChannel` uses internally — a pure query that
+ * moves nothing. Measured under gjs 1.88.1: it returns `G_IO_STATUS_NORMAL` on
+ * a regular file, on `/dev/zero` and on `/dev/null`, and THROWS
+ * `GLib.IOChannelError` ("Illegal seek") on a pty slave — cleanly, with no
+ * CRITICAL, because a `GIOChannel` over a tty is `is_seekable` and the failure
+ * comes from the kernel rather than from an assertion. Order matters: the type
+ * test runs FIRST because a FIFO / socket channel is NOT `is_seekable`, and
+ * asking one to seek is the `g_io_channel_seek_position: assertion failed`
+ * CRITICAL this function exists to avoid.
+ *
+ * Without the second test, writing to a terminal by path was impossible: the
+ * unconditional `seekFd` threw a RAW `Gio.IOErrorEnum` — `code === 8` as a
+ * NUMBER, `instanceof Error === false` — straight out of `writeFileSync`,
+ * `writeSync` and `createWriteStream`, so `catch (e) { if (e.code === 'ESPIPE') }`
+ * could not see it and the classic "write to the terminal even when stdout is
+ * redirected" idiom simply failed.
+ *
+ * The process's own stdin/stdout/stderr — the overwhelmingly common tty case —
+ * never reach this code: `isStdFd()` intercepts them first.
+ *
+ * Cached per fd: the type behind an open file description cannot change under
+ * it, and the cache is dropped by {@link releaseFd} so a recycled fd number
+ * never inherits the previous holder's answer.
+ */
+export declare function isSeekableFd(fd: number, fallbackPath: string): boolean;
+/** Absolute `lseek(2)`. Only valid on a descriptor {@link isSeekableFd} accepts. */
+export declare function seekFd(fd: number, position: number): void;
+/**
+ * The descriptor's true offset, or `null` where the host cannot report it.
+ *
+ * Only needed where the KERNEL moved the offset behind us — an `O_APPEND`
+ * write jumps to EOF without telling anyone, and computing the new position
+ * from the pre-write value is how the previous attempt let the cursor drift
+ * away from the file after the first append. `seek_position()` cannot answer
+ * this: it returns a `GIOStatus`, not an offset.
+ */
+export declare function tellFd(fd: number): number | null;
+/** `read(2)` at the descriptor's current offset. The kernel advances it. */
+export declare function readFd(fd: number, length: number): Uint8Array;
+/** `write(2)` at the descriptor's current offset. The kernel advances it. */
+export declare function writeFd(fd: number, data: Uint8Array): number;
+export declare function fsyncFd(fd: number): void;
+/**
+ * Release the cached per-fd views.
+ *
+ * The streams must go before the descriptor does: a GioUnix stream outliving
+ * its fd would answer a later call against whatever the OS handed that number
+ * to next.
+ */
+export declare function releaseFd(fd: number): void;
+/** The size of the file behind `fd`, via the descriptor where the host allows. */
+export declare function sizeOfFd(fd: number, fallbackPath: string): number;
+/**
+ * `ftruncate(2)`, as closely as GJS can express it.
+ *
+ * THE PART THAT IS REACHABLE, AND WHERE IT LIVES
+ *
+ * `ftruncate(2)` checks ONE thing: that the descriptor is open for writing. It
+ * never looks at the file's mode. That check is pure bookkeeping we already
+ * hold, so it is enforced where the access mode lives — `FileHandle`, next to
+ * the identical gates in `_readCore`/`_writeCore` — and NOT here. Without it a
+ * handle opened `'r'` could destroy the file, because the re-open below asks
+ * the kernel for its own fresh permission and gets it.
+ *
+ * THE PART THAT IS NOT, MEASURED
+ *
+ * There is no `g_ftruncate`, and no route from an fd to a `GSeekable`:
+ * `GioUnix.OutputStream` does not implement it, and `GBufferedOutputStream` /
+ * `GDataOutputStream` wrapped around one both report `can_truncate() == false`
+ * (measured under gjs 1.88.1). Truncation therefore needs a second `open(2)`,
+ * by the descriptor's procfs name so it lands on the right inode after a rename
+ * or an unlink — and a second open is checked against the FILE's mode.
+ *
+ * So the re-open takes the least privilege that can truncate: `append_to()` is
+ * `O_WRONLY`, `open_readwrite()` is `O_RDWR`. That is not a micro-optimisation
+ * — it is the difference between working and not on a write-only file: mode
+ * 0o200 truncates through the first and is refused by the second (measured).
+ * What remains unreachable is a file whose mode denies its own owner write
+ * (0o444, 0o400, 0o000): Node truncates those through the descriptor, we cannot.
+ * The failure is at least REPORTED now — it used to escape as a bare
+ * `Gio.IOErrorEnum` with a numeric `code` and `instanceof Error === false`, so
+ * `catch (e) { if (e.code === 'EACCES') }` could not see it.
+ */
+export declare function truncateFd(fd: number, length: number, fallbackPath: string): void;

package/lib/types/file-handle.d.ts

@@ -14,24 +14,28 @@ export declare class FileHandle implements IFileHandle {
         flags?: OpenFlags | number;
         mode?: Mode;
     };
-    /** Not part of the default implementation, used internal by gjsify */
-    private _file;
+    private readonly _gFile;
+    private readonly _pathStr;
+    /** What the caller asked open(2) for — the ORIGINAL flags, nothing flattened. */
+    private readonly _spec;
     /**
-     * Lazily-opened Gio streams for positional read() / write() so each call does
-     * not re-load the entire file via Gio.File.load_contents(). The IOStream is
-     * used when the handle was opened with write capability (r+, w, w+, a, a+) —
-     * it shares seek state between input and output so writes are visible to
-     * subsequent reads without a flush. For read-only handles we only open a
-     * FileInputStream; trying to open_readwrite on a read-only file can fall
-     * back to create_readwrite(REPLACE_DESTINATION) which would truncate it.
+     * The one byte position this handle has.
+     *
+     * A descriptor has exactly ONE offset, shared by reads and writes, and this
+     * is it: `_readCore`/`_writeCore` seek to it absolutely before every
+     * operation, so the kernel's own offset is a consequence of this value and
+     * can never drift away from it. It replaces four carriers that used to
+     * disagree — a read-only `_readPos`, the IOChannel's buffered offset, a
+     * cached Gio stream's cursor, and a fresh per-call stream that always
+     * started at 0.
+     *
+     * The single exception is an `O_APPEND` write: there the kernel repositions
+     * to EOF without telling us, so the new value is READ BACK rather than
+     * computed from the pre-write one. Computing it is how the previous attempt
+     * let the cursor drift away from the file after the first append.
      */
-    private _ioStream;
-    private _readStream;
-    private readonly _gFile;
-    private readonly _ioMode;
-    /** Current byte offset for `position: null` sync reads — Node advances the fd position. */
-    private _readPos;
-    private _ioLock;
+    private _pos;
+    private _closed;
     /** Not part of the default implementation, used internal by gjsify */
     private static instances;
     constructor(options: {
@@ -40,24 +44,69 @@ export declare class FileHandle implements IFileHandle {
         mode?: Mode;
     });
     /**
-     * Lazy-open the read-capable stream and return both the input stream and
-     * its seekable view. Both FileInputStream (read-only handle) and
-     * FileIOStream (read/write handle) implement Gio.Seekable, but we return
-     * both to avoid callers needing to know which concrete type they got.
+     * Read at `position`, or at the cursor when it is `null`/negative.
+     *
+     * SYNCHRONOUS ON PURPOSE. The cursor's read-modify-write — read `_pos`,
+     * seek, transfer, store `_pos` — has no `await` inside it, so it is
+     * indivisible by construction on a single-threaded runtime. The previous
+     * attempt held an async lock around the I/O but computed the offset outside
+     * it, so two concurrent writers captured the same offset and one write was
+     * lost. That class cannot exist here: there is no suspension point for
+     * anything to interleave with, which is why the async lock this replaces is
+     * gone rather than tightened.
      */
-    private _getReadStream;
-    /** Lazy-open the write-capable stream (IOStream) for this handle. Only valid
-     *  when the handle was opened with a write-capable mode. */
-    private _getWriteStream;
-    /** Serialize an async operation on the shared FileIOStream. */
-    private _serialize;
+    private _readCore;
+    /** Write at `position`, or at the cursor when it is `null`/negative. See {@link _readCore}. */
+    private _writeCore;
+    private _assertOpen;
+    /**
+     * `ftruncate(2)` — ONE body for the sync and async halves.
+     *
+     * The access-mode gate belongs HERE and not in `truncateFd`, because it is
+     * the descriptor's property and `truncateFd` has to re-open the file to do
+     * its work (see there) — a re-open that asks the kernel for its own fresh
+     * permission and is granted it. Without this line a handle opened `'r'`
+     * truncates the file: `writeFileSync(f,'ABCDEFGH'); ftruncateSync(openSync(f,'r'), 2)`
+     * destroyed six bytes through a READ-ONLY descriptor and returned normally.
+     * Node reports EINVAL, and so does this.
+     *
+     * `_readCore`/`_writeCore` have carried the identical gate since this
+     * redesign began; truncate was the one byte-mover left outside it, which is
+     * exactly the shape of divergence the single-core rule exists to prevent.
+     */
+    private _truncateCore;
+    /** Read from the cursor to EOF, advancing it — Node's whole-file read on a handle. */
+    private _readToEnd;
+    /** The path that names this DESCRIPTOR, falling back to the name it was opened from. */
+    private _fdTarget;
     /**
      * The numeric file descriptor managed by the {FileHandle} object.
      * @since v10.0.0
      */
     readonly fd: number;
-    /** Not part of the default implementation, used internal by gjsify */
-    static getInstance(fd: number): FileHandle;
+    /**
+     * The handle behind a descriptor number. Not part of Node's API.
+     *
+     * TWO things used to go wrong here, both of them at the boundary where a
+     * caller holds a NUMBER and this package holds an object.
+     *
+     * It threw `Error('No instance found for fd!')` — no `code`, not an
+     * `ErrnoException`. But the overwhelmingly common way to reach it is an fd
+     * that WAS valid: `_teardown()` deletes the instance, so every call on a
+     * closed descriptor landed here rather than on `_assertOpen`, which made
+     * that guard dead for every fd-number call site. `catch (e) { if (e.code
+     * === 'EBADF') }` — the idiom for tolerating a racing close — fell through
+     * to the generic branch instead. The syscall is threaded in from the caller
+     * because Node names it in the message, and we know it there and only there.
+     *
+     * It also indexed `instances` with whatever it was given. `openSync()`
+     * returns a FileHandle rather than Node's number (a pre-existing divergence
+     * this does not attempt to change), so `fs.write(fs.openSync(p,'w'), …)`
+     * stringified the object into a key, missed, and threw out of the callback
+     * machinery. Unwrapping is one line and makes every fd call site accept
+     * both spellings.
+     */
+    static getInstance(fd: number | FileHandle, syscall?: string): FileHandle;
     /**
      * Alias of `filehandle.writeFile()`.
      *
@@ -377,6 +426,19 @@ export declare class FileHandle implements IFileHandle {
     /** @internal */ _closeSync(): void;
     /** @internal */ _readSync(buffer: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null): number;
     /** @internal */ _writeSync(data: Uint8Array, position: number | null): number;
+    /** @internal Read from the cursor to EOF, advancing it — `readFileSync(fd)`. */ _readToEndSync(): Uint8Array;
+    /** @internal Truncate through the descriptor. */ _truncateSync(len: number): void;
+    /** @internal The path that names this descriptor — `/proc/self/fd/N` where the host has it. */
+    _fdStatTarget(): string;
+    /**
+     * Close the descriptor and deregister the handle.
+     *
+     * ONE implementation for both halves. `close()` used to leave the fd in
+     * `instances` while `_closeSync()` removed it, so every `fsPromises` close
+     * leaked its entry — and a later `openSync` reusing that fd number found a
+     * stale handle waiting for it.
+     */
+    private _teardown;
     /**
      * Closes the file handle after waiting for any pending operation on the handle to
      * complete.

package/lib/types/fs-semantics.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -13,7 +13,8 @@ import { Stats, BigIntStats } from './stats.js';
 import { Dirent } from './dirent.js';
 import { utimesSync, utimes, lutimesSync, lutimes, lchownSync, lchown, lchmodSync, lchmod } from './utimes.js';
 import { fstatSync, fstat, ftruncateSync, ftruncate, fdatasyncSync, fdatasync, fsyncSync, fsync, fchmodSync, fchmod, fchownSync, fchown, futimesSync, futimes, closeSync, readSync, writeSync, readvSync, readv, writevSync, writev, exists, openAsBlob } from './fd-ops.js';
-export declare const constants: {
+import { type PosixOpenFlags } from './posix-flags.js';
+declare const fixedConstants: {
     F_OK: number;
     R_OK: number;
     W_OK: number;
@@ -21,17 +22,6 @@ export declare const constants: {
     COPYFILE_EXCL: number;
     COPYFILE_FICLONE: number;
     COPYFILE_FICLONE_FORCE: number;
-    O_RDONLY: number;
-    O_WRONLY: number;
-    O_RDWR: number;
-    O_CREAT: number;
-    O_EXCL: number;
-    O_TRUNC: number;
-    O_APPEND: number;
-    O_SYNC: number;
-    O_NONBLOCK: number;
-    O_DIRECTORY: number;
-    O_NOFOLLOW: number;
     S_IFMT: number;
     S_IFREG: number;
     S_IFDIR: number;
@@ -53,6 +43,7 @@ export declare const constants: {
     S_IWOTH: number;
     S_IXOTH: number;
 };
+export declare const constants: typeof fixedConstants & PosixOpenFlags;
 export { FSWatcher, StatWatcher, Stats, BigIntStats, Dirent, Dir, existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, rmdirSync, unlinkSync, mkdtempSync, rmSync, statSync, openSync, realpathSync, symlinkSync, lstatSync, renameSync, copyFileSync, accessSync, appendFileSync, readlinkSync, linkSync, truncateSync, chmodSync, chownSync, cpSync, opendirSync, globSync, glob, watch, watchFile, unwatchFile, statfsSync, statfs, utimesSync, utimes, lutimesSync, lutimes, lchownSync, lchown, lchmodSync, lchmod, fstatSync, fstat, ftruncateSync, ftruncate, fdatasyncSync, fdatasync, fsyncSync, fsync, fchmodSync, fchmod, fchownSync, fchown, futimesSync, futimes, closeSync, readSync, writeSync, readvSync, readv, writevSync, writev, exists, openAsBlob, createReadStream, ReadStream, createWriteStream, WriteStream, promises, open, close, read, write, rm, realpath, readdir, symlink, lstat, stat, rename, copyFile, cp, access, appendFile, readlink, truncate, chmod, chown, mkdir, rmdir, readFile, writeFile, unlink, link, opendir, };
 declare const _default: {
     FSWatcher: typeof FSWatcher;
@@ -69,17 +60,6 @@ declare const _default: {
         COPYFILE_EXCL: number;
         COPYFILE_FICLONE: number;
         COPYFILE_FICLONE_FORCE: number;
-        O_RDONLY: number;
-        O_WRONLY: number;
-        O_RDWR: number;
-        O_CREAT: number;
-        O_EXCL: number;
-        O_TRUNC: number;
-        O_APPEND: number;
-        O_SYNC: number;
-        O_NONBLOCK: number;
-        O_DIRECTORY: number;
-        O_NOFOLLOW: number;
         S_IFMT: number;
         S_IFREG: number;
         S_IFDIR: number;
@@ -100,7 +80,7 @@ declare const _default: {
         S_IROTH: number;
         S_IWOTH: number;
         S_IXOTH: number;
-    };
+    } & PosixOpenFlags;
     existsSync: typeof existsSync;
     readdirSync: typeof readdirSync;
     readFileSync: typeof readFileSync;
@@ -139,8 +119,8 @@ declare const _default: {
     lutimes: typeof lutimes;
     lchownSync: typeof lchownSync;
     lchown: typeof lchown;
-    lchmodSync: typeof lchmodSync;
-    lchmod: typeof lchmod;
+    lchmodSync: (path: import("node:fs").PathLike, mode: number) => void;
+    lchmod: (path: import("node:fs").PathLike, mode: number, callback: (err: NodeJS.ErrnoException | null) => void) => void;
     fstatSync: typeof fstatSync;
     fstat: typeof fstat;
     ftruncateSync: typeof ftruncateSync;

package/lib/types/posix-flags.d.ts

@@ -0,0 +1,67 @@
+import type { Mode } from 'node:fs';
+import type { OpenFlags } from './types/index.js';
+/** The `O_*` bits `open(2)` understands on one host. */
+export interface PosixOpenFlags {
+    O_RDONLY: number;
+    O_WRONLY: number;
+    O_RDWR: number;
+    O_CREAT: number;
+    O_EXCL: number;
+    O_NOCTTY: number;
+    O_TRUNC: number;
+    O_APPEND: number;
+    O_NONBLOCK: number;
+    O_DSYNC: number;
+    O_SYNC: number;
+    O_DIRECTORY: number;
+    O_NOFOLLOW: number;
+}
+/**
+ * The host's `O_*` values.
+ *
+ * A function and not a module-level constant for the reason `host-os.ts`
+ * documents: `process.platform` is a lazy property installed by
+ * `@gjsify/process` at register time, so a value frozen during module
+ * evaluation can cache the byte-1 stub's answer for the life of the process.
+ */
+export declare function openFlagValues(): PosixOpenFlags;
+/** What the caller asked `open(2)` for, with nothing flattened away. */
+export interface OpenSpec {
+    /** The exact bit set to hand to `open(2)`. */
+    posix: number;
+    readable: boolean;
+    writable: boolean;
+    /** `O_APPEND` — the kernel then ignores every write position. */
+    append: boolean;
+    /** `O_CREAT` */
+    creat: boolean;
+    /** `O_CREAT | O_EXCL` — exclusivity needs BOTH, see below. */
+    excl: boolean;
+    /** `O_TRUNC` */
+    trunc: boolean;
+    /** `O_NOFOLLOW` — the open refuses a symlink instead of following it. */
+    nofollow: boolean;
+    /** `O_DIRECTORY` — the open refuses anything that is not a directory. */
+    directory: boolean;
+}
+/** Translate Node open flags into the exact `open(2)` argument. */
+export declare function parseOpenFlags(flags: OpenFlags | number | string | undefined | null): OpenSpec;
+/**
+ * Node's `mode` argument as a number.
+ *
+ * Node documents `mode` as `string | integer` and parses a string as OCTAL —
+ * a plain numeric cast turns `'600'` into decimal 600 = `0o1130` (sticky plus
+ * `--x-wx---`), so the caller cannot read back the file it just created. One
+ * parser, shared by open / mkdir / mkdtemp / writeFile / appendFile / chmod,
+ * because the two that disagreed were the two that drifted.
+ *
+ * `fallback` is used only when `mode` is absent, and it is OPTIONAL because not
+ * every caller has one: Node's `open`/`mkdir`/`writeFile` document a default,
+ * and `chmod` does NOT — its `mode` is required, and Node rejects a missing one
+ * with `ERR_INVALID_ARG_TYPE`. Handing `chmod` a 0o666 default here made
+ * `fs.chmodSync(p, cfg.mode)` with an absent `cfg.mode` silently WIDEN a 0600
+ * secret to world-writable, from the shared parser this redesign introduced to
+ * stop the two spellings drifting. `0` is a VALID mode and must survive: the
+ * old `options.mode ||= 0o666` silently replaced it.
+ */
+export declare function normalizeMode(mode: Mode | undefined | null, fallback?: number): number;

package/lib/types/promises.d.ts

@@ -81,7 +81,11 @@ declare function mkdtemp(prefix: string, options: BufferEncodingOption): Promise
  * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
  */
 declare function mkdtemp(prefix: string, options?: ObjectEncodingOptions | BufferEncoding | null): Promise<string | Buffer>;
-declare function writeFile(path: PathLike, data: string | Uint8Array | unknown): Promise<void>;
+declare function writeFile(path: PathLike | FileHandle, data: string | Uint8Array | unknown, options?: {
+    encoding?: string | null;
+    mode?: Mode;
+    flag?: OpenFlags | string;
+} | string | null): Promise<void>;
 /**
  * Removes the directory identified by `path`.
  *
@@ -125,7 +129,7 @@ declare function rm(path: PathLike, options?: RmOptions): Promise<void>;
 declare function rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
 declare function copyFile(src: PathLike, dest: PathLike, mode?: number): Promise<void>;
 declare function access(path: PathLike, mode?: number): Promise<void>;
-declare function appendFile(path: PathLike, data: string | Uint8Array, options?: {
+declare function appendFile(path: PathLike | FileHandle, data: string | Uint8Array, options?: {
     encoding?: string;
     mode?: number;
     flag?: string;

package/lib/types/read-stream.d.ts

@@ -2,22 +2,83 @@ import { Buffer } from 'node:buffer';
 import { Readable } from 'node:stream';
 import type { CreateReadStreamOptions } from 'node:fs/promises';
 import type { PathLike, ReadStream as IReadStream } from 'node:fs';
+/**
+ * What `fs.createReadStream()` accepts, as opposed to
+ * `filehandle.createReadStream()`.
+ *
+ * `CreateReadStreamOptions` is the fs/promises shape and has no `fd` — which is
+ * exactly why one was never read here, and why this stream had no way to reach
+ * a descriptor at all.
+ */
+export type ReadStreamOptions = CreateReadStreamOptions & {
+    fd?: number | null;
+};
 export declare class ReadStream extends Readable implements IReadStream {
     bytesRead: number;
     path: string | Buffer;
     pending: boolean;
     fd: number | null;
+    /**
+     * Read through the DESCRIPTOR rather than by opening the path again.
+     *
+     * `filehandle.createReadStream()` returned a stream that opened the path
+     * afresh at offset 0: a second read cursor that neither consulted nor
+     * advanced the handle's. After `await fh.read(buf,0,4,null)` the stream
+     * replayed the whole file from the beginning where Node resumes at byte 4,
+     * and it bound a different inode if the path had been replaced since the
+     * open. The write half was moved onto the descriptor earlier in this
+     * redesign, so until now the "one cursor" invariant held for writes only.
+     */
+    private _ownFd;
+    private _autoCloseFd;
+    /** Whether reads carry an explicit position (`start` given) or ride the shared cursor. */
+    private _positional;
     private _gioFile;
     private _inputStream;
     private _cancellable;
     private _start;
     private _end;
     private _pos;
+    /**
+     * Whether a `read_bytes_async` is in flight.
+     *
+     * A `GInputStream` allows exactly ONE outstanding async operation; a second
+     * one fails with `G_IO_ERROR_PENDING` ("Datenstrom hat noch einen
+     * ausstehenden Vorgang"). Nothing here used to prevent the second call, and
+     * the only thing that kept it rare was that the write side of a pipe took a
+     * main-loop turn to acknowledge each chunk. The moment writes stopped
+     * needing one, `pipe()` of a 128 KB file started failing about two runs in
+     * three — a race that was always there, timed out of reach.
+     *
+     * So the invariant is enforced rather than relied on: a `_read()` that
+     * arrives mid-flight is remembered and re-issued on completion instead of
+     * being dropped (which would stall the stream) or issued (which throws).
+     */
+    private _reading;
+    private _readAgain;
+    private _lastSize;
     close(callback?: (err?: NodeJS.ErrnoException | null) => void): void;
-    constructor(path: PathLike, opts?: CreateReadStreamOptions);
+    constructor(path: PathLike, opts?: ReadStreamOptions);
     _construct(callback: (err?: Error | null) => void): void;
     _read(size: number): void;
     private _doRead;
+    /**
+     * One chunk through the descriptor, on the handle's own cursor.
+     *
+     * `position: null` when the caller gave no `start`, so the read advances
+     * the shared offset exactly as `fh.read()` would and the stream picks up
+     * where the last operation left off. With a `start` the reads are
+     * positional (`pread`), which by the same core leaves the cursor alone —
+     * Node's rule, verified against it.
+     *
+     * The `end` bound is applied HERE rather than in `_doRead`, because the
+     * descriptor path is scheduled and `_doRead` no longer knows the cursor's
+     * value at the moment the read actually happens.
+     */
+    private _readThroughFd;
+    /** Every OS resource this stream holds, released once and idempotently. */
+    private _release;
+    private _releaseFd;
     _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
 }
-export declare function createReadStream(path: string | URL, options?: CreateReadStreamOptions): ReadStream;
+export declare function createReadStream(path: string | URL, options?: ReadStreamOptions): ReadStream;

package/lib/types/stats.d.ts

@@ -65,3 +65,25 @@ export declare class BigIntStats extends Dirent implements NodeBigIntStats {
     constructor(info: Gio.FileInfo, path: PathLike, filename?: string);
     constructor(path: PathLike, filename?: string);
 }
+/**
+ * A `Stats` for `info`, or the error the kernel actually gave.
+ *
+ * `g_file_query_info()` does NOT fail when the kernel refuses to stat a name —
+ * a path under a directory this process cannot search comes back as a non-NULL
+ * `GFileInfo` carrying no attributes at all (see {@link answered}, where the
+ * measurement lives). Every stat entry point built a `Stats` straight from
+ * whatever it got, and that is two failures in one call: reading the type and
+ * the size off the empty shell logs four `GLib-GIO-CRITICAL` lines — a SIGABRT
+ * under `G_DEBUG=fatal-criticals` — and what it then returns is a FABRICATED
+ * `{mode: 0, size: 0, ino: 0, nlink: 0}` presented as fact, where Node raises
+ * EACCES. A caller checking `statSync(p).mode & 0o200` before writing is told
+ * the file is unwritable rather than that it may not look; one checking
+ * `.size` is told the file is empty.
+ *
+ * All five GJS-side call sites (`statSync`, `lstatSync`, the `stat`/`lstat`
+ * callbacks, `fsPromises.stat` and `filehandle.stat()`) go through here, so the
+ * gate cannot be present in four of them and missing in the fifth — which is
+ * how it got here: the open path grew {@link answered} in this same redesign
+ * and the stat path, which asks the identical question, did not.
+ */
+export declare function statsFrom(info: Gio.FileInfo, pathStr: string, syscall: string, bigint?: boolean): Stats | BigIntStats;