claw-store/Cargo.toml

@@ -34,9 +34,11 @@ default = []
 # Phase 6: enables the claw-fuse binary + pulls in the fuser dep.
 fuse = ["dep:fuser"]
 
-[target.'cfg(target_os = "linux")'.dependencies]
-# v0.15 — Rust FUSE bindings. Only pulled on Linux + only when
-# the `fuse` feature is on; keeps macOS + non-fuse builds clean.
+[target.'cfg(any(target_os = "linux", target_os = "macos"))'.dependencies]
+# v0.15 — Rust FUSE bindings. Pulled on Linux + macOS when the
+# `fuse` feature is on. macOS additionally requires macFUSE
+# (https://osxfuse.github.io) — install via `brew install --cask
+# macfuse` before building with --features fuse.
 fuser = { version = "0.15", optional = true }
 
 [dependencies]

deploy/macos/README.md

@@ -0,0 +1,74 @@
+# macOS setup (ghost, macbook, smith)
+
+The `claw-fuse` binary supports macOS via [macFUSE](https://osxfuse.github.io).
+macFUSE requires a kernel extension approval on first install — the
+user has to click through System Settings → Privacy & Security →
+Allow, then reboot. This is one-time.
+
+## One-time prereqs
+
+```bash
+# macFUSE (kernel extension). Requires admin password + a reboot.
+brew install --cask macfuse
+
+# pkg-config so the fuser crate can discover macFUSE headers.
+brew install pkg-config
+```
+
+After the reboot, verify:
+
+```bash
+pkg-config --modversion fuse    # or `osxfuse` on older installs
+```
+
+## Build the binary
+
+```bash
+cd path/to/clawstor
+cargo build --release --features fuse --bin claw-fuse
+```
+
+If pkg-config can't find `fuse`, the build will panic with an
+unhelpful message from fuser's build.rs. Confirm the pkg-config
+check first.
+
+## Mount
+
+Same CLI as Linux:
+
+```bash
+mkdir -p ~/clawstor-mount
+target/release/claw-fuse \
+  --data-dir /path/to/clawstor/data \
+  --mount ~/clawstor-mount
+```
+
+## Unmount
+
+```bash
+umount ~/clawstor-mount
+# or, if the process is still running:
+diskutil unmount force ~/clawstor-mount
+```
+
+## launchd auto-mount (optional)
+
+Copy [claw-fuse.plist](claw-fuse.plist) into
+`~/Library/LaunchAgents/`, edit the paths to match, then:
+
+```bash
+launchctl load ~/Library/LaunchAgents/dev.clawstor.claw-fuse.plist
+launchctl start dev.clawstor.claw-fuse
+ls ~/clawstor-mount/
+```
+
+Unload with `launchctl unload ~/Library/LaunchAgents/dev.clawstor.claw-fuse.plist`.
+
+## Known differences from Linux mount
+
+* No `AllowOther` support on macFUSE by default — the mount is
+  visible only to the mounting user unless you set
+  `allow_other` in `/etc/fuse.conf` (macFUSE 4.x).
+* Read-only enforcement is honored the same way. `read` /
+  `readdir` / `getattr` work identically.
+* Unmount is `umount` (BSD) not `fusermount3 -u` (Linux).

deploy/macos/claw-fuse.plist

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  launchd agent for the read-only claw-fuse mount on macOS.
+
+  Install:
+    cp deploy/macos/claw-fuse.plist ~/Library/LaunchAgents/dev.clawstor.claw-fuse.plist
+    launchctl load ~/Library/LaunchAgents/dev.clawstor.claw-fuse.plist
+
+  Edit ProgramArguments to match your local paths. `RunAtLoad` +
+  `KeepAlive` mean the mount survives logouts/reboots the same way
+  the Linux systemd unit does.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>dev.clawstor.claw-fuse</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/YOU/clawstor-deploy/claw-fuse</string>
+        <string>--data-dir</string>
+        <string>/Users/YOU/clawstor-deploy/data</string>
+        <string>--mount</string>
+        <string>/Users/YOU/clawstor-mount</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+
+    <!-- Give the process the user's PATH + a real home. -->
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/claw-fuse.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/claw-fuse.stderr.log</string>
+</dict>
+</plist>

deploy/systemd/README.md

@@ -13,9 +13,9 @@ Systemd **user** units for clawstor.
 | `clawstor-ref-sweep.service` + `clawstor-ref-sweep.timer` | Nightly (03:15) Gitea live-refs poll + stale-fingerprint report. Set `GITEA_TOKEN` via a drop-in for private repos. Report-only (dry-run) — deletion is a follow-on. |
 | `clawstor-snapshot-rotate.service` + `clawstor-snapshot-rotate.timer` | Daily (02:00) create `daily-YYYY-MM-DD` snapshot + prune snapshots older than `RETAIN_DAYS` (default 30). Only touches snapshots whose name matches `daily-*` — hand-created ones survive. |
 
-## Install `clawstor-fuse.service`
+## Install `clawstor-fuse.service` (Linux)
 
-Prereqs: `libfuse3` installed, `claw-fuse` binary built with
+Prereqs: `libfuse3-dev` + `pkg-config` installed, `claw-fuse` binary built with
 `cargo build --release --features fuse --bin claw-fuse`.
 
 ```bash