@photostructure/fs-metadata 1.3.0 → 1.4.1

package/AGENTS.md

@@ -0,0 +1,213 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+@photostructure/fs-metadata - Cross-platform native Node.js module for filesystem metadata retrieval.
+
+### Directory Structure
+
+- `src/` - Source code (TypeScript and C++)
+- `dist/` - Compiled JavaScript output (gitignored)
+- `doc/` - Static documentation (manually written, checked into git)
+- `build/` - All build artifacts (gitignored)
+  - `build/docs/` - Generated API documentation from TypeDoc (deployed to GitHub Pages)
+- `scripts/` - Build and utility scripts
+- `prebuilds/` - Prebuilt native binaries for different platforms
+
+### Script Preferences
+
+**Always** use TypeScript (`.ts`) scripts executed with `tsx` instead of:
+
+- `.js` scripts (require compilation or older Node.js syntax)
+- `.mjs` scripts (ESM-only, compatibility issues)
+- `.cjs` scripts (CommonJS-only, less type safety)
+
+TypeScript with tsx provides type safety, modern syntax, and seamless execution.
+
+## Critical Knowledge
+
+### Testing File System Metadata
+
+**Never** expect exact equality for dynamic values (`available`, `used`) between calls. Only verify:
+
+- Value exists and has correct type: `typeof result.available === 'number'`
+- Test static properties (`size`, `mountFrom`, `fstype`) for exact equality
+- Avoid range assertions (`available > 0`) - file changes can be dramatic
+
+### Cross-Module Compatibility
+
+Use `_dirname()` from `./dirname` instead of `__dirname` - works in both CommonJS and ESM contexts.
+
+### Node.js Version Compatibility
+
+Jest 30 doesn't support Node.js 23. Use Node.js 20, 22, or 24.
+
+## System Volume Detection
+
+**IMPORTANT: Read `doc/system-volume-detection.md` before modifying any system volume detection logic.** It documents the full detection strategy across all platforms, including flag matrices and rationale for each approach.
+
+Summary:
+
+- The root `/` is a sealed, read-only APFS snapshot whose **UUID changes on every OS update** — never use it for persistent identification.
+- **Primary detection** combines mount flags with APFS volume roles: `MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")`. See `ClassifyMacVolume()` in `src/darwin/system_volume.h`.
+- The APFS role string is exposed as `volumeRole` on `MountPoint` and `VolumeMetadata`.
+- **Fallback** uses `MNT_SNAPSHOT` only from `statfs` `f_flags` if DA session creation fails.
+- `MNT_DONTBROWSE` is safe to use **only when combined with a non-Data APFS role**. The Data volume (`/System/Volumes/Data`) has `MNT_DONTBROWSE` but role `"Data"`, so it is correctly excluded.
+- Pseudo-filesystems like `devfs` (no IOMedia, no APFS role) are caught by TypeScript fstype/path heuristics.
+
+## Windows-Specific Issues
+
+### Windows CI Jest Worker Failures
+
+**Problem**: Jest worker processes fail on Windows CI environments (both x64 and ARM64) with "Jest worker encountered 4 child process exceptions".
+
+**Solution for Memory Tests**:
+
+Memory tests now use a standalone TypeScript runner (`src/test-utils/memory-test-runner.ts`) that bypasses Jest entirely on all platforms. This provides more accurate memory measurements without Jest overhead and avoids worker process issues.
+
+- Run full memory check suite (includes native tools): `npm run check:memory`
+- Memory test logic is in `src/test-utils/memory-test-core.ts`
+
+**Workaround for Other Tests**:
+
+1. Jest is configured to use single worker mode (`maxWorkers: 1`) for all Windows CI environments
+2. Tests that stress worker threads or concurrency are skipped on Windows CI using `describeSkipWindowsCI` or `describePlatformStable`:
+
+- `worker_threads.test.ts` - Worker thread integration tests
+- `thread_safety.test.ts` - Concurrent operations stress tests
+- `windows-memory-check.test.ts` - Memory leak detection (Windows only)
+- `windows-resource-security.test.ts` - Resource handle leak tests (Windows only)
+
+**Note**: These tests pass locally but fail in CI. The native module loads correctly, but Jest's worker process management has fundamental incompatibilities with these specific tests on GitHub Actions Windows runners.
+
+### Build Architecture Issue
+
+**Problem**: "No Target Architecture" error from Windows SDK headers when building with node-gyp/prebuildify.
+
+**Solution**: Use `scripts/prebuildify-wrapper.ts` which sets the `CL` environment variable with architecture defines:
+
+- For x64: `CL=/D_M_X64 /D_WIN64 /D_AMD64_`
+- For ARM64: `CL=/D_M_ARM64 /D_WIN64`
+
+**Why This is Necessary**:
+
+- Prebuildify doesn't properly pass architecture defines from binding.gyp conditions
+- The Windows SDK requires these macros before including `<windows.h>`
+- Projects like node-sqlite avoid this by not using Windows headers directly
+
+**Why Other Approaches Failed**:
+
+- **Source file defines**: Would hardcode x64 defines, breaking ARM64 builds
+- **windows_compat.h wrapper**: Can't distinguish x64 from ARM64 at compile time
+- **binding.gyp conditions**: Not evaluated properly by prebuildify
+- **msvs_settings defines**: Not passed through to the compiler
+
+### Memory Testing Limitations
+
+Traditional Windows tools **do not work** with Node.js native modules:
+
+- **Dr. Memory**: Fails with "Unable to load client library: ucrtbase.dll"
+- **Debug CRT builds**: Cannot be loaded by Node.js (missing debug runtime + UNC path issues)
+- **Visual Leak Detector**: Requires debug builds which don't work
+- **Application Verifier**: Cannot hook into Node.js memory management
+
+Use JavaScript-based memory testing (`src/windows-memory-check.test.ts`) instead.
+
+### Static Analysis (clang-tidy) Limitations
+
+**clang-tidy on Windows** has limited effectiveness due to MSVC header incompatibility:
+
+- Generates many false errors about missing std namespace members
+- Still provides valuable warnings about your code
+- See `doc/windows-clang-tidy.md` for details
+- Consider using Visual Studio Code Analysis as an alternative
+
+### WSL Development
+
+Run Windows commands from WSL:
+
+```bash
+cmd.exe /c "cd C:\\Users\\matth\\src\\fs-metadata && npm test"
+# Or create helper: echo 'cmd.exe /c "cd C:\\Users\\matth\\src\\fs-metadata && $@"' > ~/bin/win-run
+```
+
+## Memory Leak Detection
+
+Run `npm run check:memory` for comprehensive platform-specific testing:
+
+- **All platforms**: JavaScript memory tests with GC triggers
+- **Windows**: Handle count monitoring via `process.report`
+- **Linux**: Valgrind + AddressSanitizer/LeakSanitizer
+- **macOS**: AddressSanitizer (may fail due to SIP - expected)
+
+## CI/CD Test Reliability
+
+### Critical Anti-Patterns
+
+**Never** use these to "fix" async issues:
+
+```javascript
+// BAD: Arbitrary timeouts
+await new Promise((resolve) => setTimeout(resolve, 100));
+// BAD: Forcing GC
+if (global.gc) global.gc();
+// BAD: setImmediate in afterAll
+afterAll(async () => {
+  await new Promise((resolve) => setImmediate(resolve));
+});
+```
+
+### Windows Directory Cleanup
+
+Always use retry logic:
+
+```typescript
+await fsp.rm(tempDir, {
+  recursive: true,
+  force: true,
+  maxRetries: process.platform === "win32" ? 3 : 1,
+  retryDelay: process.platform === "win32" ? 100 : 0,
+});
+```
+
+### Platform Performance Multipliers
+
+- Alpine Linux (musl): 2x slower
+- ARM64 emulation: 5x slower
+- Windows processes: 4x slower
+- macOS VMs: 4x slower
+
+### Multi-Process Synchronization
+
+Use explicit signals:
+
+```javascript
+console.log("READY"); // Signal readiness
+console.log("RESULT:" + outcome); // Signal result
+```
+
+## Release Process
+
+Requires repository secrets:
+
+- `NPM_TOKEN`: npm authentication
+- `GPG_PRIVATE_KEY`: ASCII-armored GPG key
+- `GPG_PASSPHRASE`: GPG passphrase
+
+Automated via GitHub Actions workflow dispatch or manual:
+
+```bash
+npm run prepare-release
+git config commit.gpgsign true
+npm version patch|minor|major
+npm publish
+git push origin main --follow-tags
+```
+
+## General guidance
+
+Never do inline imports like `const { mkdirSync } = await import("node:fs");` -- just use standard imports.
+
+**NEVER** add "Generated with Codex" or "Co-Authored-By: Codex" lines to git commit messages. Keep commits clean and professional.

package/CHANGELOG.md

@@ -14,6 +14,60 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 1.4.1 - 2026-04-27
+
+### Fixed
+
+- **SIGABRT during Node.js environment teardown.** In-flight async workers
+  (DiskArbitration/IOKit calls on macOS, and the equivalent paths on Linux
+  and Windows) could complete after `node::FreeEnvironment` had begun
+  teardown. The default `node-addon-api` completion path then threw a C++
+  `Napi::Error` out of a libuv cleanup-hook frame with no catch, causing
+  `terminate()` / abort.
+
+  All async workers now derive from a new `SafeAsyncWorker` base that
+  tracks per-env shutdown state via napi instance data plus
+  `napi_add_env_cleanup_hook`. During teardown, completion callbacks
+  short-circuit and deferred resolve/reject calls are wrapped to swallow
+  teardown-time napi failures (the JS-side promise is unobservable at
+  that point anyway). Long-running uncancellable native calls
+  (`IOServiceGetMatchingService`, drive-status probes) also bail out as
+  soon as the shutdown flag flips, so process exit isn't dragged out by
+  in-flight work.
+
+  No public API changes.
+
+## 1.4.0 - 2026-04-20
+
+### Removed
+
+- **Linux GIO/GLib integration removed.** The optional `enable_gio` build-time
+  flag, the `getGioMountPoints` native binding, and the entire `src/linux/gio_*`
+  source tree have been deleted. The Linux mount-points and volume-metadata
+  paths now use `/proc/self/mounts` parsing exclusively.
+
+  Background: GIO was originally added to surface auto-mounted volumes (USB
+  sticks, external SSDs) that appeared to be missing from `/proc/mounts`. The
+  earlier mount-table read order has since been fixed, and direct verification
+  on Ubuntu 24 confirmed that udisks2-mounted devices (`/media/$USER/...`) are
+  fully visible via `/proc/self/mounts` without GIO. The remaining GIO code
+  path was a thin wrapper around `g_unix_mounts_get()` (which itself reads
+  `/proc/self/mountinfo`) — functionally redundant with the existing mtab
+  parser. The GVolumeMonitor enrichment path that originally justified GIO had
+  already been removed for thread-safety reasons in an earlier release.
+
+  Net effect: smaller native module, no `libglib2.0-dev` build dependency, no
+  `libgio` runtime dependency, simpler Linux build matrix. No public API
+  changes — `getVolumeMountPoints()` and `getVolumeMetadata()` return the same
+  data as before.
+
+### Changed
+
+- Linux build no longer requires `libglib2.0-dev`. Only `libblkid-dev` (and
+  `uuid-dev` for the dev environment) is needed when compiling from source.
+- `scripts/setup-native.mjs` removed — its only purpose was GIO autodetection.
+  `npm run build` and `npm run build:native` no longer invoke it.
+
 ## 1.3.0 - 2026-03-26
 
 ### Added

package/CONTRIBUTING.md

@@ -41,7 +41,7 @@ Install the Xcode Command Line Tools, and then
 
 ### On Ubuntu/Debian
 
-    sudo apt-get install bear build-essential clang-format libglib2.0-dev libblkid-dev uuid-dev
+    sudo apt-get install bear build-essential clang-format libblkid-dev uuid-dev
 
 ## Before submitting your PR
 
@@ -57,7 +57,7 @@ into account both Windows and POSIX systems.
 
 - macOS on x86 and Apple Silicon
 - Windows on x64
-- glibc Linux on x64 and arm64, with or without Gnome GIO support
+- glibc Linux on x64 and arm64
 - MUSL Alpine Linux on x64 and arm64
 
 ## Development Gotchas
@@ -121,7 +121,7 @@ Actions that have multiple targets can be run in parallel using wildcards:
 
 ### Naming Guidelines
 
-- Use explicit names to avoid ambiguity (e.g., `setup:native` instead of just `setup`)
+- Use explicit names to avoid ambiguity (e.g., `build:native` instead of just `build`)
 - Group related scripts by action prefix for easy wildcard execution
 - Avoid names that could cause npm lifecycle conflicts (e.g., `prebuild` vs `build`)
 - Use descriptive suffixes that clearly indicate the target or purpose

package/binding.gyp

@@ -1,7 +1,4 @@
 {
-  "variables": {
-    "enable_gio%": "false"
-  },
   "targets": [
     {
       "target_name": "fs_metadata",
@@ -57,25 +54,6 @@
                   "cflags": ["-mbranch-protection=standard"],
                   "cflags_cc": ["-mbranch-protection=standard"]
                 }
-              ],
-              [
-                "enable_gio=='true'",
-                {
-                  "sources": [
-                    "src/linux/gio_utils.cpp",
-                    "src/linux/gio_mount_points.cpp",
-                    "src/linux/gio_volume_metadata.cpp"
-                  ],
-                  "defines": [
-                    "ENABLE_GIO=1"
-                  ],
-                  "libraries": [
-                    "<!@(pkg-config --libs gio-unix-2.0)"
-                  ],
-                  "cflags": [
-                    "<!@(pkg-config --cflags gio-unix-2.0)"
-                  ]
-                }
               ]
             ]
           }

package/dist/index.cjs

@@ -694,11 +694,6 @@ async function* readLinks(directory) {
 // src/linux/mount_points.ts
 var import_promises4 = require("fs/promises");
 
-// src/mount_point.ts
-function isMountPoint(obj) {
-  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
-}
-
 // src/options.ts
 var import_node_os2 = require("os");
 var import_node_process3 = require("process");
@@ -1180,49 +1175,25 @@ function parseMtab(content) {
 }
 
 // src/linux/mount_points.ts
-async function getLinuxMountPoints(native, opts) {
+async function getLinuxMountPoints(opts) {
   const o = optionsWithDefaults(opts);
-  const raw = [];
-  try {
-    const arr = await (await native()).getGioMountPoints?.();
-    debug("[getLinuxMountPoints] GIO mount points: %o", arr);
-    if (arr != null) raw.push(...arr);
-  } catch (error) {
-    debug("Failed to get GIO mount points: %s", error);
-  }
   let cause;
   for (const input of o.linuxMountTablePaths) {
     try {
       const mtabContent = await (0, import_promises4.readFile)(input, "utf8");
-      const arr = parseMtab(mtabContent).map((ea) => mountEntryToMountPoint(ea)).filter((ea) => ea != null);
-      debug("[getLinuxMountPoints] %s mount points: %o", input, arr);
-      if (arr.length > 0) {
-        raw.push(...arr);
-        break;
+      const results = parseMtab(mtabContent).map((ea) => mountEntryToMountPoint(ea)).filter((ea) => ea != null);
+      debug("[getLinuxMountPoints] %s mount points: %o", input, results);
+      if (results.length > 0) {
+        return results;
       }
     } catch (error) {
       cause ??= toError(error);
     }
   }
-  const byMountPoint = /* @__PURE__ */ new Map();
-  for (const ea of raw) {
-    const prior = byMountPoint.get(ea.mountPoint);
-    const merged = { ...compactValues(prior), ...compactValues(ea) };
-    if (isMountPoint(merged)) {
-      byMountPoint.set(merged.mountPoint, merged);
-    }
-  }
-  if (byMountPoint.size === 0) {
-    throw new WrappedError(
-      `Failed to find any mount points (tried: ${JSON.stringify(o.linuxMountTablePaths)})`,
-      { cause }
-    );
-  }
-  const results = [...byMountPoint.values()];
-  debug("[getLinuxMountPoints] %o", {
-    results: results.map((ea) => ea.mountPoint)
-  });
-  return results;
+  throw new WrappedError(
+    `Failed to find any mount points (tried: ${JSON.stringify(o.linuxMountTablePaths)})`,
+    { cause }
+  );
 }
 async function getLinuxMtabMetadata(mountPoint, opts) {
   let caughtError;
@@ -1349,7 +1320,7 @@ async function _getVolumeMountPoints(o, nativeFn2) {
       points.length
     );
     return points;
-  })() : getLinuxMountPoints(nativeFn2, o));
+  })() : getLinuxMountPoints(o));
   debug("[getVolumeMountPoints] raw mount points: %o", raw);
   const compacted = raw.map((ea) => compactValues(ea)).filter((ea) => isNotBlank(ea.mountPoint));
   for (const ea of compacted) {