@photostructure/fs-metadata 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -14,6 +14,50 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 1.1.0 - 2026-03-16
+
+### Added
+
+- New `getVolumeMetadataForPath(pathname)` function: given any file or directory path, returns the `VolumeMetadata` for the volume that contains it. Mirrors the behavior of `df pathname`:
+  - Resolves POSIX symlinks via `realpath()`
+  - On **macOS**: uses `fstatfs()` `f_mntonname` to correctly resolve APFS firmlinks (e.g. `/Users` → `/System/Volumes/Data`) — `stat().dev` does not follow firmlinks and would give the wrong result
+  - On **Linux**: uses `stat().dev` device ID matching with path-prefix disambiguation for bind mounts and GIO mounts that share a device ID. Also works correctly in Docker containers, where `/proc/self/mounts` reflects the container's mount namespace.
+  - On **Windows**: uses device ID and path-prefix matching against logical drives
+
+- New `isReadOnly` field on `MountPoint` (and by extension `VolumeMetadata`) indicating whether a volume is mounted read-only. This is useful for identifying volumes with unstable UUIDs, like the macOS APFS system snapshot at `/`, whose UUID changes on every OS update. Available on all platforms:
+  - **macOS**: reads `MNT_RDONLY` from `statfs` flags
+  - **Linux**: parses `ro` from mount options in `/proc/mounts`
+  - **Windows**: checks `FILE_READ_ONLY_VOLUME` from `GetVolumeInformation`
+
+### Changed
+
+- **macOS `isSystemVolume` detection now uses APFS volume roles via IOKit** instead of path pattern heuristics. Each APFS volume has a role (System, Data, VM, Preboot, Recovery, etc.) stored in its superblock. We read this via `DADiskCopyIOMedia()` → `IORegistryEntryCreateCFProperty("Role")`, with a `MNT_SNAPSHOT` fallback if DiskArbitration is unavailable. This is factual (Apple assigns the roles), not heuristic, and correctly distinguishes:
+  - `/` (System role) → `isSystemVolume: true` — sealed OS snapshot, unstable UUID
+  - `/System/Volumes/Data` (Data role) → `isSystemVolume: false` — primary user data volume
+  - `/System/Volumes/VM`, `Preboot`, `Update`, `Hardware`, `xarts`, etc. → `isSystemVolume: true`
+  - See [`doc/system-volume-detection.md`](./doc/system-volume-detection.md) for full details
+
+### Security
+
+- macOS: RAII wrapper (`IOObjectGuard`) for IOKit objects in APFS volume role detection, preventing Mach port resource leaks if exceptions occur during `GetApfsVolumeRole()`
+- macOS: DiskArbitration operations in `getVolumeMountPoints()` now serialize through the same `g_diskArbitrationMutex` used by `getVolumeMetadata()`, preventing potential data races when both APIs are called concurrently
+- See [`doc/SECURITY_AUDIT_2026.md`](./doc/SECURITY_AUDIT_2026.md) for full audit details
+
+### Fixed
+
+- Zero-initialized `VolumeMetadata` size/used/available fields to prevent uninitialized values when volume info retrieval fails early
+- Windows: eliminated redundant `GetVolumeInformationW` call per drive in `getVolumeMountPoints()`
+
+### Removed
+
+- Removed macOS `/System/Volumes/*` path patterns from `SystemPathPatternsDefault` — these are now handled natively via APFS volume roles. The Spotlight, FSEvents, and Trashes glob patterns (`**/.Spotlight-V100`, `**/.fseventsd`, etc.) were also removed as they matched directories within volumes, not mount points.
+
+## 1.0.1 - 2026-03-01
+
+### Fixed
+
+- `isHidden()` and `getHiddenMetadata()` now return `false` for root directories on all platforms. Windows root drives (e.g. `C:\`) have `FILE_ATTRIBUTE_HIDDEN` set by default as a system quirk, not user intent.
+
 ## 1.0.0 - 2026-02-23
 
 ### Security

package/CLAUDE.md

@@ -44,6 +44,19 @@ Use `_dirname()` from `./dirname` instead of `__dirname` - works in both CommonJ
 
 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

package/claude.sh

@@ -1,14 +1,31 @@
 #!/bin/bash
 
-# To make sure we use this if available:
-# alias claude='if [ -f "./claude.sh" ]; then ./claude.sh; else command claude; fi'
+# Claude Code wrapper: appends a project-specific system prompt to every session.
+#
+# Appends TPP instructions and mandatory guidelines via --append-system-prompt.
+# See https://photostructure.com/coding/claude-code-tpp/ for details.
+#
+# Setup: add this function to your ~/.bashrc, ~/.bash_aliases, or ~/.zshrc:
+#
+#   cla() {
+#     if [ -f "./claude.sh" ]; then ./claude.sh "$@"; else command claude "$@"; fi
+#   }
+#
+# Usage:
+#   cla               # Starts a TPP-aware session
+#   cla --resume      # Resume with TPP context
+#   claude update     # Vanilla claude still works for non-TPP use
+#
+# The --append-system-prompt below is also a good place to add brief,
+# high-value instructions that Claude tends to ignore in CLAUDE.md.
+# Keep it concise! Every token here reduces your available context window.
 
-echo "Adding our system prompt..."
+echo "Adding project system prompt..."
 
 DATE=$(date +%Y-%m-%d)
 
-claude --append-system-prompt "$(
-  cat <<'EOF'
+command claude --append-system-prompt "$(
+  cat <<EOF
 # MANDATORY GUIDELINES
 - **Study your CLAUDE.md** - Every conversation begins by studying CLAUDE.md
 - **Always Start By Reading** - You must study the referenced codebase and related documentation before making any change. NEVER assume APIs or implementation details.
@@ -22,5 +39,12 @@ claude --append-system-prompt "$(
 - **It's YOUR JOB to keep docs current** - If your edits change **any** behavior or type signatures, search and update both code comments and documentation and edit them to reflect those changes.
 - **Do not delete files without asking** - If you need to delete a file, please ask for permission first, and provide a justification for why it should be deleted.
 - The current date is $DATE -- it is not 2024.
+
+# TECHNICAL PROJECT PLANS (TPPs)
+This project uses Technical Project Plans (TPPs) in \`_todo/*.md\` to share research, design decisions, and next steps between sessions.
+
+- When you exit plan mode, your first step should be to write or update a relevant TPP using the /handoff skill.
+- When you run low on context and you are working on a TPP, run the /handoff skill.
+- Check \`_todo/\` at the start of every session for active TPPs relevant to the current task.
 EOF
 )" "$@"

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   getHiddenMetadata: () => getHiddenMetadata,
   getTimeoutMsDefault: () => getTimeoutMsDefault,
   getVolumeMetadata: () => getVolumeMetadata,
+  getVolumeMetadataForPath: () => getVolumeMetadataForPath,
   getVolumeMountPoints: () => getVolumeMountPoints,
   isHidden: () => isHidden,
   isHiddenRecursive: () => isHiddenRecursive,
@@ -460,6 +461,11 @@ function isRootDirectory(path) {
   const n = normalizePath(path);
   return n == null ? false : isWindows ? (0, import_node_path3.dirname)(n) === n : n === "/";
 }
+function isAncestorOrSelf(ancestor, descendant) {
+  if (ancestor === descendant) return true;
+  const prefix = isRootDirectory(ancestor) ? ancestor : ancestor + import_node_path3.sep;
+  return descendant.startsWith(prefix);
+}
 
 // src/hidden.ts
 var HiddenSupportByPlatform = {
@@ -493,6 +499,10 @@ async function isHiddenImpl(pathname, nativeFn2) {
     throw new Error("Invalid pathname: " + JSON.stringify(pathname));
   }
   debug("Normalized path: %s", norm);
+  if (isRootDirectory(norm)) {
+    debug("Root directory, returning false");
+    return false;
+  }
   debug(
     "LocalSupport: dotPrefix=%s, systemFlag=%s",
     LocalSupport.dotPrefix,
@@ -565,6 +575,14 @@ async function getHiddenMetadataImpl(pathname, nativeFn2) {
   if (norm == null) {
     throw new Error("Invalid pathname: " + JSON.stringify(pathname));
   }
+  if (isRootDirectory(norm)) {
+    return {
+      hidden: false,
+      dotPrefix: false,
+      systemFlag: false,
+      supported: LocalSupport
+    };
+  }
   const dotPrefix = isPosixHidden(norm);
   const systemFlag = await isSystemHidden(norm, nativeFn2);
   return {
@@ -674,23 +692,13 @@ var SystemPathPatternsDefault = [
   "/mnt/wslg/doc",
   "/mnt/wslg/versions.txt",
   "/usr/lib/wsl/drivers",
-  // macOS system paths:
-  "/private/var/vm",
-  // macOS swap
-  "/System/Volumes/Hardware",
-  "/System/Volumes/iSCPreboot",
-  "/System/Volumes/Preboot",
-  "/System/Volumes/Recovery",
-  "/System/Volumes/Reserved",
-  "/System/Volumes/Update",
-  "/System/Volumes/VM",
-  "/System/Volumes/xarts",
-  // macOS per-volume metadata (Spotlight, FSEvents, versioning, Trash):
-  // https://eclecticlight.co/2021/01/28/spotlight-on-search-how-spotlight-works/
-  "**/.DocumentRevisions-V100",
-  "**/.fseventsd",
-  "**/.Spotlight-V100",
-  "**/.Trashes"
+  // macOS system volumes are detected natively via APFS volume roles
+  // (IOKit IOMedia "Role" property) with MNT_SNAPSHOT as a fallback.
+  // No path patterns needed. See src/darwin/system_volume.h.
+  //
+  // /private/var/vm is the macOS swap directory (not a mount point on most
+  // systems, but included for completeness if it appears as one).
+  "/private/var/vm"
 ];
 var SystemFsTypesDefault = [
   "autofs",
@@ -865,6 +873,10 @@ async function directoryStatus(dir, timeoutMs, canReaddirImpl = canReaddir) {
   return { status: VolumeHealthStatuses.unknown };
 }
 
+// src/volume_metadata.ts
+var import_promises5 = require("fs/promises");
+var import_node_path6 = require("path");
+
 // src/linux/dev_disk.ts
 var import_promises3 = require("fs/promises");
 var import_node_path5 = require("path");
@@ -1149,20 +1161,20 @@ function isSystemVolume(mountPoint, fstype, config = {}) {
 }
 function assignSystemVolume(mp, config) {
   const result = isSystemVolume(mp.mountPoint, mp.fstype, config);
-  if (isWindows) {
-    mp.isSystemVolume ??= result;
-  } else {
-    mp.isSystemVolume = result;
-  }
+  mp.isSystemVolume = mp.isSystemVolume || result;
 }
 
 // src/linux/mtab.ts
+function isReadOnlyMount(fs_mntops) {
+  return fs_mntops?.split(",").includes("ro") ?? false;
+}
 function mountEntryToMountPoint(entry) {
   const mountPoint = normalizePosixPath(entry.fs_file);
   const fstype = toNotBlank(entry.fs_vfstype) ?? toNotBlank(entry.fs_spec);
   return mountPoint == null || fstype == null ? void 0 : {
     mountPoint,
-    fstype
+    fstype,
+    isReadOnly: isReadOnlyMount(entry.fs_mntops)
   };
 }
 function mountEntryToPartialVolumeMetadata(entry, options = {}) {
@@ -1172,6 +1184,7 @@ function mountEntryToPartialVolumeMetadata(entry, options = {}) {
     fstype: entry.fs_vfstype,
     mountFrom: entry.fs_spec,
     isSystemVolume: isSystemVolume(entry.fs_file, entry.fs_vfstype, options),
+    isReadOnly: isReadOnlyMount(entry.fs_mntops),
     remote: false,
     // < default to false, but it may be overridden by extractRemoteInfo
     ...extractRemoteInfo(entry.fs_spec, networkFsTypes)
@@ -1455,6 +1468,57 @@ async function _getVolumeMetadata(o, nativeFn2) {
   debug("[getVolumeMetadata] final result for %s: %o", o.mountPoint, result);
   return compactValues(result);
 }
+async function getVolumeMetadataForPathImpl(pathname, opts, nativeFn2) {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+  const resolved = await (0, import_promises5.realpath)(pathname);
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : (0, import_node_path6.dirname)(resolved);
+  if (isMacOS) {
+    const probe = await getVolumeMetadataImpl(
+      { ...opts, mountPoint: dir },
+      nativeFn2
+    );
+    const canonicalMountPoint = isNotBlank(probe.mountName) ? probe.mountName : dir;
+    if (canonicalMountPoint === dir) return probe;
+    return getVolumeMetadataImpl(
+      { ...opts, mountPoint: canonicalMountPoint },
+      nativeFn2
+    );
+  }
+  const targetDev = resolvedStat.dev;
+  const mountPoints = await getVolumeMountPointsImpl(
+    { ...opts, includeSystemVolumes: true },
+    nativeFn2
+  );
+  const prefixMatches = [];
+  const deviceMatches = [];
+  await Promise.all(
+    mountPoints.map(async ({ mountPoint: mountPoint2 }) => {
+      try {
+        const mpDev = (await statAsync(mountPoint2)).dev;
+        if (mpDev !== targetDev) return;
+        if (isAncestorOrSelf(mountPoint2, resolved)) {
+          prefixMatches.push(mountPoint2);
+        } else {
+          deviceMatches.push(mountPoint2);
+        }
+      } catch {
+      }
+    })
+  );
+  const candidates = prefixMatches.length > 0 ? prefixMatches : deviceMatches;
+  if (candidates.length === 0) {
+    throw new Error(
+      "No mount point found for path: " + JSON.stringify(pathname)
+    );
+  }
+  const mountPoint = candidates.reduce(
+    (a, b) => a.length >= b.length ? a : b
+  );
+  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn2);
+}
 async function getAllVolumeMetadataImpl(opts, nativeFn2) {
   const o = optionsWithDefaults(opts);
   debug("[getAllVolumeMetadata] starting with options: %o", o);
@@ -1510,11 +1574,11 @@ async function getAllVolumeMetadataImpl(opts, nativeFn2) {
 var nativeFn = defer2(async () => {
   const start = Date.now();
   try {
-    const dirname4 = _dirname();
-    const dir = await findAncestorDir(dirname4, "binding.gyp");
+    const dirname5 = _dirname();
+    const dir = await findAncestorDir(dirname5, "binding.gyp");
     if (dir == null) {
       throw new Error(
-        "Could not find bindings.gyp in any ancestor directory of " + dirname4
+        "Could not find bindings.gyp in any ancestor directory of " + dirname5
       );
     }
     const bindings = (0, import_node_gyp_build.default)(dir);
@@ -1537,6 +1601,13 @@ function getVolumeMetadata(mountPoint, opts) {
     nativeFn
   );
 }
+function getVolumeMetadataForPath(pathname, opts) {
+  return getVolumeMetadataForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn
+  );
+}
 function getAllVolumeMetadata(opts) {
   return getAllVolumeMetadataImpl(optionsWithDefaults(opts), nativeFn);
 }
@@ -1566,6 +1637,7 @@ function setHidden(pathname, hidden, method = "auto") {
   getHiddenMetadata,
   getTimeoutMsDefault,
   getVolumeMetadata,
+  getVolumeMetadataForPath,
   getVolumeMountPoints,
   isHidden,
   isHiddenRecursive,