@photostructure/fs-metadata 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -14,7 +14,13 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
-## [0.6.0] - 2025-06-03
+## 0.7.0 - 2025-10-24
+
+- Audit and address [several resource handling issues](./doc/SECURITY_AUDIT_2025.md)
+- Added support for Node.js v25
+- Updated dev dependencies
+
+## 0.6.0 - 2025-06-09
 
 ### Added
 
@@ -24,6 +30,8 @@ Security in case of vulnerabilities.
 - Clang-tidy integration for C++ code analysis
 - Worker thread helper for volume metadata operations
 - NAPI_VERSION=9 definition for improved compatibility
+- Dynamic test timeout configuration based on environment (CI, platform, architecture)
+- Prebuild script for Linux GLIBC compatibility in Docker environments
 
 ### Breaking
 
@@ -36,6 +44,7 @@ Security in case of vulnerabilities.
 - Updated all imports to use `node:` prefix for built-in modules
 - Reorganized build and test scripts for better clarity
 - Improved memory test workflow for cross-platform compatibility
+- Renamed native module target from `node_fs_meta` to `fs_metadata` for consistency
 
 ### Fixed
 
@@ -44,13 +53,9 @@ Security in case of vulnerabilities.
 - Fixed buffer allocation issues in Windows networking and volume operations
 - Enhanced resource management with better validation for empty mount points
 - Made `SystemPathPatternsDefault` values visible in TypeScript typings
-- Improved test reliability across different CI environments
 - Added Napi::HandleScope to OnOK and OnError methods for proper scope management
 - Removed unnecessary std::move operations in worker implementations
-- Updated filesystem metadata tests to verify type and existence instead of specific values
-- Improved error handling and messages in various components
-- Enhanced error message validation for file access in worker thread tests
-- Updated tests to use healthy mount points for volume metadata retrieval
+- Resolved CI test reliability issues across different environments, particularly Alpine ARM64 emulation timeouts
 
 ## [0.4.0] - 2025-01-09
 

package/CLAUDE.md

@@ -4,173 +4,197 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is @photostructure/fs-metadata - a cross-platform native Node.js module for retrieving filesystem metadata, including mount points, volume information, and space utilization statistics.
-
-### Key Features
-- Cross-platform support: Windows 10+ (x64), macOS 14+, Ubuntu 22+ (x64, arm64)
-- Lists all mounted volumes/drives
-- Gets detailed volume metadata (size, usage, filesystem type, etc.)
-- Hidden file/directory attribute support (get/set)
-- Non-blocking async native implementations
-- Timeout handling for unresponsive network volumes
-- ESM and CJS module support
-- Full TypeScript type definitions
-- Worker threads support with proper context isolation
-
-### Platform-Specific Notes
-- **Linux**: Optional GIO/GVfs mount support via Gnome libraries
-- **Windows**: Uses separate threads per mountpoint for health checks to handle blocked system calls
-- **System Volumes**: Each platform handles system volumes differently; the library uses heuristics to identify them
-
-## Common Commands
-
-### Build and Development
-```bash
-# Install dependencies and build native modules
-npm install
+@photostructure/fs-metadata - Cross-platform native Node.js module for filesystem metadata retrieval.
 
-# Configure platform-specific build settings
-npm run configure:native
+### Directory Structure
 
-# Build native bindings
-npm run node-gyp-rebuild
+- `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
 
-# Create prebuilds for distribution  
-npm run prebuild
+### Script Preferences
 
-# Assemble TypeScript to dist/
-npm run build:dist
-```
+**Always** use TypeScript (`.ts`) scripts executed with `tsx` instead of:
 
-### Testing
-```bash
-# Run all tests with coverage (includes memory tests on Linux)
-npm run test:all
+- `.js` scripts (require compilation or older Node.js syntax)
+- `.mjs` scripts (ESM-only, compatibility issues)
+- `.cjs` scripts (CommonJS-only, less type safety)
 
-# Run CommonJS tests
-npm test:cjs
+TypeScript with tsx provides type safety, modern syntax, and seamless execution.
 
-# Run ESM tests
-npm test:esm
+## Critical Knowledge
 
-# Test memory leaks (JavaScript)
-npm run test:memory
+### Testing File System Metadata
 
-# Run valgrind memory analysis (Linux only)
-bash scripts/valgrind-test.sh
+**Never** expect exact equality for dynamic values (`available`, `used`) between calls. Only verify:
 
-# Run AddressSanitizer and LeakSanitizer (Linux only)
-bash scripts/sanitizers-test.sh
+- 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
 
-# Run comprehensive memory tests (JavaScript + valgrind + sanitizers)
-npm run test:memory
+### Cross-Module Compatibility
 
-# Run a specific test file (no coverage)
-npm test volume_metadata
-```
+Use `_dirname()` from `./dirname` instead of `__dirname` - works in both CommonJS and ESM contexts.
 
-### Code Quality
-```bash
-# Run ESLint
-npm run lint
+### Node.js Version Compatibility
 
-# Fix ESLint issues
-npm run lint:fix
+Jest 30 doesn't support Node.js 23. Use Node.js 20, 22, or 24.
 
-# Format code (all formats)
-npm run fmt
+## Windows-Specific Issues
 
-# Format C++ code only
-npm run fmt:cpp
+### Windows CI Jest Worker Failures
 
-# Format TypeScript only
-npm run fmt:ts
+**Problem**: Jest worker processes fail on Windows CI environments (both x64 and ARM64) with "Jest worker encountered 4 child process exceptions".
 
-# Type checking
-npm run build:ts
-```
+**Solution for Memory Tests**:
 
-### Pre-commit
-```bash
-# Full precommit check (fmt, clean, prebuild, tests)
-npm run precommit
-```
+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:
 
-### Documentation
 ```bash
-# Generate API documentation
-npm run docs
+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
 ```
 
-## Architecture Overview
+## Memory Leak Detection
 
-### Core Structure
-- **Native binding layer** (`src/binding.cpp`): Node-API v9 bridge between JavaScript and platform-specific implementations
-- **Platform abstractions** in `src/common/`: Shared C++ interfaces for cross-platform functionality
-- **Platform implementations**:
-  - `src/darwin/`: macOS-specific code using Core Foundation APIs
-  - `src/linux/`: Linux-specific code with optional GIO support for GNOME/GVfs
-  - `src/windows/`: Windows-specific code using Win32 APIs
+Run `npm run check:memory` for comprehensive platform-specific testing:
 
-### Key Features
-- **Volume Metadata**: Retrieves filesystem information (mount points, disk usage, health status)
-- **Hidden File Support**: Cross-platform hidden file detection and manipulation
-- **Async Operations**: All native operations use Worker threads to avoid blocking
+- **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)
 
-### Build System
-- Uses `node-gyp` for native compilation
-- Conditionally enables GIO support on Linux via `scripts/configure.mjs`
-- Provides prebuilt binaries via `prebuildify` for common platforms
-- Supports both ESM and CJS module formats
+## CI/CD Test Reliability
 
-### Cross-Module Compatibility
-- **Directory Path Resolution**: Use `_dirname()` from `./dirname` instead of `__dirname`
-  - Works in both CommonJS and ESM contexts
-  - Handles Jest test environments correctly
-  - Example: `const dir = _dirname()` instead of `const dir = __dirname`
+### Critical Anti-Patterns
 
-### Testing Strategy
-- Jest for both CJS and ESM test suites
-- Platform-specific test expectations handled via `isWindows`, `isMacOS`, `isLinux` helpers
-- Memory leak testing with garbage collection monitoring
-- Coverage thresholds: 80% for all metrics
+**Never** use these to "fix" async issues:
 
-### Testing File System Metadata
-- **Important**: File system metadata like `available` space, `used` space, and other dynamic properties change continuously as other processes run on the machine
-- Tests should **never** expect exact equality for these values between multiple calls
-- **Do not** make range assertions (e.g., `available > 0` or `used < size`) because:
-  - Files can be created or deleted between calls (potentially gigabytes)
-  - The changes can be dramatic and unpredictable
-- Instead, for dynamic metadata:
-  - Only verify the value exists and has the correct type
-  - Use `typeof result.available === 'number'` rather than range checks
-  - Focus on testing static properties (e.g., `size`, `mountFrom`, `fstype`) for exact equality
-  - Consider using snapshot testing only for stable properties
-
-### Timeout Handling
-- Default timeout for volume operations to handle unresponsive network mounts
-- Windows uses separate threads per mountpoint for health checks
-- Configurable via `Options` interface
-
-### Debug Logging
-- Enable with `NODE_DEBUG=fs-meta` or `NODE_DEBUG=photostructure:fs-metadata`
-- Debug messages from both JavaScript and native code are sent to `stderr`
-- Uses native Node.js debuglog for determining if logging is enabled
-
-## Example Usage
+```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
-import { getVolumeMountPoints, getVolumeMetadata } from "@photostructure/fs-metadata";
+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
+```
 
-// List all mounted volumes
-const mountPoints = await getVolumeMountPoints();
-console.dir({ mountPoints });
+## General guidance
 
-// Get metadata for a specific volume
-const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
-console.dir({ volumeMetadata });
+Never do inline imports like `const { mkdirSync } = await import("node:fs");` -- just use standard imports.
 
-// Check if a file is hidden
-import { isHidden } from "@photostructure/fs-metadata";
-const hidden = await isHidden("/path/to/file");
-```
+Never include claude code messages in git commits

package/CODE_OF_CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the
+- Focusing on what is best not just for us as individuals, but for the
   overall community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or
+- The use of sexualized language or imagery, and sexual attention or
   advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
   address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior,  harassment of an
+standards, including sustained inappropriate behavior, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within

package/CONTRIBUTING.md

@@ -26,7 +26,7 @@ Install the Xcode Command Line Tools, and then
 
 ### On Ubuntu/Debian
 
-    sudo apt-get install build-essential clang-format libglib2.0-dev libblkid-dev uuid-dev
+    sudo apt-get install bear build-essential clang-format libglib2.0-dev libblkid-dev uuid-dev
 
 ## Before submitting your PR
 
@@ -106,7 +106,7 @@ Actions that have multiple targets can be run in parallel using wildcards:
 
 ### Naming Guidelines
 
-- Use explicit names to avoid ambiguity (e.g., `configure:native` instead of just `configure`)
+- Use explicit names to avoid ambiguity (e.g., `setup:native` instead of just `setup`)
 - 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/README.md

@@ -1,55 +1,19 @@
-# @photostructure/fs-metadata
+![PhotoStructure fs-metadata logo](https://raw.githubusercontent.com/photostructure/fs-metadata/main/doc/logo.svg)
 
-A cross-platform native Node.js module for retrieving filesystem metadata, including mount points, volume information, and space utilization statistics.
-
-Built and supported by [PhotoStructure](https://photostructure.com).
+Cross-platform native Node.js module for filesystem metadata, mount points, and volume information.
 
 [![npm version](https://img.shields.io/npm/v/@photostructure/fs-metadata.svg)](https://www.npmjs.com/package/@photostructure/fs-metadata)
 [![Build](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml)
-[![GitHub issues](https://img.shields.io/github/issues/photostructure/fs-metadata.svg)](https://github.com/photostructure/fs-metadata/issues)
-[![Known Vulnerabilities](https://snyk.io/test/github/photostructure/fs-metadata/badge.svg?targetFile=package.json)](https://snyk.io/test/github/photostructure/fs-metadata?targetFile=package.json)
 [![Node-API v9 Badge](https://raw.githubusercontent.com/nodejs/abi-stable-node/refs/heads/doc/assets/Node-API%20v9%20Badge.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix)
 [![View on GitHub](https://img.shields.io/badge/View%20on-GitHub-blue)](https://github.com/photostructure/fs-metadata)
 
-## Features
-
-- Cross-platform support:
-  - Windows 10+ (x64)
-  - macOS 14+
-  - Ubuntu 22+ (x64, arm64) (with Gnome GIO/`GVfs` mount support where available)
-
-- [List all mounted volumes/drives](https://photostructure.github.io/fs-metadata/functions/getVolumeMountPoints.html)
-
-- [Get detailed volume metadata](https://photostructure.github.io/fs-metadata/functions/getVolumeMetadata.html)
-
-- File and directory hidden attribute support:
-  - [Get](https://photostructure.github.io/fs-metadata/functions/isHidden.html) and [set](https://photostructure.github.io/fs-metadata/functions/setHidden.html) hidden attributes
-  - POSIX-style support (macOS and Linux)
-  - Filesystem metadata support (macOS and Windows)
-  - [Recursive hidden checks](https://photostructure.github.io/fs-metadata/functions/isHiddenRecursive.html)
-  - [Hidden metadata queries](https://photostructure.github.io/fs-metadata/functions/getHiddenMetadata.html)
-
-- ESM and CJS support
-
-- Full TypeScript type definitions
-
-- Non-blocking async native implementations
-
-- Timeout handling for wedged network volumes
-
-- Compatible with all current Node.js and Electron versions via [Node-API v9](https://nodejs.org/api/n-api.html#node-api) and [prebuildify](https://github.com/prebuild/prebuildify)
-
-- Comprehensive test coverage
-
-## Installation
+## Quick Start
 
 ```bash
 npm install @photostructure/fs-metadata
 ```
 
-## Usage
-
-```ts
+```typescript
 import {
   getVolumeMountPoints,
   getVolumeMetadata,
@@ -57,62 +21,48 @@ import {
 
 // List all mounted volumes
 const mountPoints = await getVolumeMountPoints();
-console.dir({ mountPoints });
+console.log(mountPoints);
 
 // Get metadata for a specific volume
-const volumeMetadata = await getVolumeMetadata(mountPoints[0]);
-console.dir({ volumeMetadata });
+const metadata = await getVolumeMetadata("/");
+console.log(metadata);
 ```
 
-If you're using CommonJS:
-
-```js
-const {
-  getVolumeMountPoints,
-  getVolumeMetadata,
-} = require("@photostructure/fs-metadata");
-
-// Usage is the same as the ESM example above 
-// (except of course no top-level awaits!)
-```
-
-## API
-
-[Read the API here](https://photostructure.github.io/fs-metadata/modules.html)
-
-## Options
-
-### Debug Logging
-
-Set `NODE_DEBUG=fs-meta` or `NODE_DEBUG=photostructure:fs-metadata`. The native [debuglog](https://nodejs.org/api/util.html#utildebuglogsection-callback) determines if debug logging is enabled. Debug messages from both JavaScript and native code are sent to `stderr`.
-
-### Timeouts
-
-Operations use a [default timeout](https://photostructure.github.io/fs-metadata/variables/TimeoutMsDefault.html), which may need adjustment for slower devices like optical drives (which can take 30+ seconds to spin up).
-
-Windows can block system calls when remote filesystems are unhealthy due to host downtime or network issues. To handle this, we use a separate thread per mountpoint to check volume health status. While this approach uses more resources than the async N-API thread, it enables reliable timeouts for operations that would otherwise hang indefinitely.
-
-Timeout duration may apply per-operation or per-system call, depending on the implementation.
+## Key Features
 
-### System Volumes
+- **Volume Management**: List mount points, get volume metadata, space usage
+- **Hidden Files**: Get/set hidden attributes, recursive checks, cross-platform support
+- **Performance**: Non-blocking async operations with timeout protection
+- **TypeScript**: Full type definitions with ESM and CommonJS support
 
-Each platform handles system volumes differently:
+## Supported Platforms
 
-- Windows provides explicit metadata for "system" or "reserved" devices, though `C:\` is both a system volume and typical user storage
-- Linux and macOS include various system-only mountpoints: pseudo devices, snap loopback devices, virtual memory partitions, and recovery partitions
+| Platform      | Architecture | Node.js | OS Version                |
+| ------------- | ------------ | ------- | ------------------------- |
+| Windows       | x64, arm64   | 20+     | Windows 10+               |
+| macOS         | x64, arm64   | 20+     | macOS 14+                 |
+| Linux (glibc) | x64, arm64   | 20+     | Debian 11+, Ubuntu 20.04+ |
+| Linux (musl)  | x64, arm64   | 20+     | Alpine 3.21+              |
 
-This library uses heuristics to identify system volumes. See [Options](https://photostructure.github.io/fs-metadata/interfaces/Options.html) for default values and customization.
+> **Note**: Linux binaries require GLIBC 2.31+. The `node:20` Docker image is not supported.
 
-Note: [`getAllVolumeMetadata()`](https://photostructure.github.io/fs-metadata/functions/getAllVolumeMetadata.html) returns all volumes on Windows but only non-system volumes elsewhere by default.
+## Documentation
 
-## License
+- 📖 [API Reference](https://photostructure.github.io/fs-metadata/modules.html)
+- 💡 [Examples](./doc/examples.md) - Common usage patterns and recipes
+- ⚠️ [Gotchas](./doc/gotchas.md) - Platform quirks, timeouts, and troubleshooting
+- 🔧 [Contributing](./CONTRIBUTING.md) - Build instructions and development guide
 
-This project is licensed under the [MIT License](https://github.com/photostructure/fs-metadata/blob/main/LICENSE.txt).
+### Options
 
-## Contributing
+- **Debug**: Set `NODE_DEBUG=fs-meta` for debug output
+- **Timeouts**: Configure [timeout duration](https://photostructure.github.io/fs-metadata/variables/TimeoutMsDefault.html) for slow devices
+- **System Volumes**: Control [system volume filtering](https://photostructure.github.io/fs-metadata/interfaces/Options.html)
 
-We welcome contributions! Please see our [Contributing Guide](https://github.com/photostructure/fs-metadata/blob/main/CONTRIBUTING.md) for more details.
+## Support
 
-## Security
+Built and supported by [PhotoStructure](https://photostructure.com)
 
-For security-related issues, please refer to our [Security Policy](https://github.com/photostructure/fs-metadata/blob/main/SECURITY.md).
+- [GitHub Issues](https://github.com/photostructure/fs-metadata/issues)
+- [Security Policy](./SECURITY.md)
+- [MIT License](./LICENSE.txt)