@photostructure/fs-metadata 1.4.0 → 2.0.0

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,52 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 2.0.0 - 2026-06-03
+
+### Changed
+
+- **BREAKING: Minimum supported Node.js raised to v22.** `engines.node` is now
+  `>=22` (previously `>=20.0.0`). Node.js 20 and 21 are no longer supported. The
+  supported matrix is now Node.js 22, 24, and 26. This drop is what makes the
+  release a major version; there are no breaking changes to the public runtime
+  API.
+
+- **Dual type declarations for ESM and CommonJS.** The build now emits separate
+  `index.d.cts` and `index.d.mts` declaration files, and the package `exports`
+  map points each module system at its matching types. This fixes type
+  resolution under `"moduleResolution": "node16"`/`"nodenext"` consumers. The
+  build is now verified with [`@arethetypeswrong/cli`](https://arethetypeswrong.github.io/),
+  and dual-declaration generation plus export checks (`check:exports`) run as
+  part of the precommit/lint pipeline.
+
+### Fixed
+
+- **`statAsync` now passes `throwIfNoEntry`** to comply with the updated Node.js
+  `fs.stat` signature, avoiding a deprecation/typing mismatch on newer runtimes.
+
+## 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

package/CLAUDE.md

@@ -42,7 +42,7 @@ Use `_dirname()` from `./dirname` instead of `__dirname` - works in both CommonJ
 
 ### Node.js Version Compatibility
 
-Jest 30 doesn't support Node.js 23. Use Node.js 20, 22, or 24.
+Jest 30 doesn't support Node.js 23. Use Node.js 22, 24, or 26.
 
 ## System Volume Detection