dsh-locator 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.1 — 2026-11-09
+
+* Engine version is injected at build time (`-X main.version`) instead of a hard-coded `0.1.0`; `locator_status` now reports the package version.
+* `locator_export` verified against the live 1.24 M-entry index: 1,238,602 rows, 477 MB, 6.4 s.
+* Memory tuning documented: Go honours `GOMEMLIMIT` / `GOGC`, so the engine can be capped without a rebuild (e.g. `GOMEMLIMIT=600MiB`).
+
+## 0.4.0 — 2026-11-09
+
+* macOS now ships **FSEvents** in the cgo darwin binaries (arm64 and x64): a pure-C stream callback serializes events into a pipe, so the recursive watcher has no per-directory descriptor limit. The previous crash was `FSEventStreamCreate` receiving the callback context instead of a real `FSEventStreamContext`.
+* kqueue remains the `CGO_ENABLED=0` fallback and is used by the cross-built binaries in custom builds.
+* CI builds the cgo darwin binaries on the macOS runner and the FSEvents create/delete test runs there.
+* Replaces the 0.3.0 darwin binaries with the cgo builds; other platforms are unchanged.
+
 ## 0.3.0 — 2026-11-09
 
 * Web panel: double-click a row to reveal it in the platform file manager (Explorer `/select`, Finder `open -R`, `xdg-open` on the directory). The path must be inside the configured roots and is passed as an argument vector, never through a shell; failure falls back to copying the path.

package/README-zh.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
 [![ci](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml)
 
-中文 | [English](README.md)
+[English](README.md) | [中文](README-zh.md) | [Español](README-es.md) | [Português](README-pt.md) | [हिन्दी](README-hi.md)
 
 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的全盘毫秒级文件搜索，**自建索引**：不装 Everything、不用 `es.exe`、不需要 Everything 服务。
 
@@ -97,7 +97,7 @@ npm 包内置 `linux-x64`、`linux-arm64`、`win32-x64`、`win32-arm64`、`darwi
 | `roots` | `[]` | 要索引的目录；空 = 用户主目录。 |
 | `excludes` | 开发/缓存目录 | 扫描与监听都跳过的基础名 glob。 |
 | `watch` | `true` | 启用原生文件系统通知。 |
-| `refreshIntervalMs` | `1800000` | 没有原生监听时（目前是 macOS）的重建周期；0 关闭。 |
+| `refreshIntervalMs` | `1800000` | 没有原生监听时（kqueue 回退或监听失败）的重建周期；0 关闭。 |
 | `scanWorkers` | `0` | 扫描时的目录读取并发；0 = CPU 数。 |
 | `windowsUsn` | `false` | 扫描时先试 NTFS USN/MFT 枚举（Windows，需管理员；失败自动回退）。 |
 | `stateDir` | `''` | 快照目录；空 = 平台缓存目录。 |
@@ -114,7 +114,7 @@ npm 包内置 `linux-x64`、`linux-arm64`、`win32-x64`、`win32-arm64`、`darwi
 |---|---|---|---|
 | Linux | 是 | inotify，递归 | 每个目录一个 watch；极大目录树可能撞 `fs.inotify.max_user_watches`。 |
 | Windows | 是 | `ReadDirectoryChangesW`，递归 | 不需要管理员，不需要 Everything。提权时可选用 USN/MFT 枚举。WSL 写 `/mnt/<盘>` 可能不产生 Windows 通知，用 `locator_rebuild` 补。 |
-| macOS | 是 | kqueue vnode 监听（最多 4,096 个目录）+ 周期性重建 | 目录级事件覆盖新建、删除、重命名；文件内容变化不产生 vnode 事件，大小/时间由 `refreshIntervalMs` 或 `locator_rebuild` 刷新。 |
+| macOS | 是 | 随包发布的 cgo 二进制使用 FSEvents（递归、无上限） | `CGO_ENABLED=0` 构建回退到 kqueue（最多 4,096 个目录）；回退模式下内容变化仍由 `refreshIntervalMs` 或 `locator_rebuild` 刷新。 |
 
 引擎是纯 Go、无 cgo，一台机器交叉编译全部平台；运行时从不需要管理员权限。
 
@@ -202,7 +202,7 @@ pnpm build:engine:all   # 或 build:engine 只构建本机
 * Linux inotify 每个目录一个描述符；几十万目录的主目录可能超过内核上限。插件会报警告，快照仍可用，重建可以补齐。
 * WSL 写 `/mnt/c` 可能不产生 Windows 侧通知（Windows 监听看不到 9p 写入方的变更流），需显式重建。
 * 网络共享只有在能当普通目录访问时才会被扫描；没有 SMB 专用变更源。
-* macOS 是目录级监听（kqueue，每目录一个描述符，上限 4,096）：新建/删除/重命名即时生效；文件内容变化靠周期重建。无上限、文件级的 FSEvents 仍在路线图。
+* macOS 随包二进制使用 FSEvents（递归）；`CGO_ENABLED=0` 构建回退到 kqueue（每目录一个描述符，上限 4,096）。两种模式的内容变更都靠周期重建兜底。
 * 还没有 USN/MFT 快速枚举（见上）。
 
 ## 路线图
@@ -213,6 +213,10 @@ pnpm build:engine:all   # 或 build:engine 只构建本机
 4. 可选的小写名字 arena 与 trigram 预筛。
 5. 增量快照压缩与按根目录的日志。
 
+## 内存
+
+引擎是单个 Go 进程，遵循标准 `GOMEMLIMIT` / `GOGC` 环境变量。124 万条索引在默认 GC 下峰值约 700–800MB RSS；内存紧张时设 `GOMEMLIMIT=600MiB`（软上限，运行时用 CPU 换内存）或 `GOGC=50`。都不改变快照格式。
+
 ## 安全与隐私
 
 索引完全本地：不联网、不埋点、不上传。快照里是文件名和路径，请把状态目录当私有数据；介意的话别把它纳入备份。插件绝不修改、移动或删除被索引的文件。

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
 [![ci](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-locator/actions/workflows/ci.yml)
 
-[中文](README-zh.md) | English
+[English](README.md) | [中文](README-zh.md) | [Español](README-es.md) | [Português](README-pt.md) | [हिन्दी](README-hi.md)
 
 A whole-disk, millisecond file search for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that builds its **own** index. No Everything installation, no `es.exe`, no Everything service.
 
@@ -97,7 +97,7 @@ Every field is a Schemastery config field; edit the `dsh-locator` entry in the p
 | `roots` | `[]` | Directories to index; empty means the home directory. |
 | `excludes` | dev/cache directories | Base-name globs skipped by scanner and watcher. |
 | `watch` | `true` | Apply native filesystem notifications. |
-| `refreshIntervalMs` | `1800000` | Rebuild cadence when no native watcher exists (macOS today); `0` disables. |
+| `refreshIntervalMs` | `1800000` | Rebuild cadence when no native watcher is active (kqueue fallback or a watcher failure); `0` disables. |
 | `scanWorkers` | `0` | Directory reader concurrency during scans; `0` uses the CPU count. |
 | `windowsUsn` | `false` | Try the NTFS USN/MFT enumeration before the walk (Windows, administrator; falls back automatically). |
 | `stateDir` | `''` | Snapshot directory; empty means the platform cache directory. |
@@ -114,9 +114,9 @@ Narrow `roots` if indexing the whole home directory is too much I/O. A small, fo
 |---|---|---|---|
 | Linux | yes | inotify, recursive | Watch descriptors are per directory; very large trees can hit `fs.inotify.max_user_watches`. |
 | Windows | yes | `ReadDirectoryChangesW`, recursive | No admin rights and no Everything needed. Optional USN/MFT enumeration when running elevated. Changes made by WSL to `/mnt/<drive>` may not raise notifications; use `locator_rebuild` for those. |
-| macOS | yes | kqueue vnode watches for up to 4,096 directories, plus periodic rebuild | Directory-level events cover creates, deletes and renames. File content changes do not raise vnode events, so size/mtime refresh comes from `refreshIntervalMs` or `locator_rebuild`. |
+| macOS | yes | FSEvents in the shipped cgo binaries, recursive and uncapped | kqueue is the `CGO_ENABLED=0` fallback (up to 4,096 directories). File content changes do not raise vnode events in the fallback, so size/mtime refresh comes from `refreshIntervalMs` or `locator_rebuild`. |
 
-The engine is pure Go with no cgo, cross-compiled from one machine. It never needs admin privileges.
+The engine is pure Go except the macOS FSEvents backend, which uses cgo and is built on a macOS runner. Linux, Windows and the kqueue fallback build with `CGO_ENABLED=0`; USN is optional and needs admin rights, everything else does not.
 
 ### Windows and the USN journal
 
@@ -202,17 +202,21 @@ The engine is a separate Go module under `engine/`; run its tests with `cd engin
 * Linux inotify watches one descriptor per directory; a home directory with hundreds of thousands of directories can exceed the kernel limit. The plugin reports the warning and the snapshot stays usable; rebuilds catch up.
 * WSL writes into `/mnt/c` may not produce Windows notifications (the Windows watcher cannot see the 9p writer's change stream). Rebuild those roots explicitly.
 * Network shares are scanned only if they are reachable as ordinary directories; no SMB-specific change feed.
-* macOS watches are directory-level (kqueue, one descriptor per directory, capped at 4,096). Creates/deletes/renames land immediately; file content changes rely on the periodic rebuild. FSEvents remains the roadmap item for an uncapped, file-level feed.
-* No USN/MFT fast enumeration yet (see above).
+* macOS uses FSEvents (recursive) in the shipped binaries; a `CGO_ENABLED=0` build falls back to kqueue, capped at 4,096 directories. Content-only changes rely on the periodic rebuild either way.
+* Windows USN/MFT is optional and only used when the process can read the volume and the journal is active; otherwise the portable walk is used.
 
 ## Roadmap
 
-1. macOS FSEvents watcher.
-2. Windows USN/MFT fast enumeration when the process can read the volume; journal-based catch-up after downtime.
-3. Dedicated Web GUI panel (table, sortable columns, filters, preview, insert-as-`@file`).
+1. USN journal catch-up after downtime (persist the journal cursor and FRN map).
+2. Panel actions: insert a result as `@file`, richer previews.
+3. More platform runtime coverage (Electron desktop, Windows on ARM).
 4. Optional lowercase-name arena and trigram prefilter for large indexes.
 5. Incremental snapshot compaction and per-root journals.
 
+## Memory
+
+The engine is a single Go process and honours the standard `GOMEMLIMIT` and `GOGC` environment variables. A 1.24 M-entry index peaks around 700–800 MB RSS with the default GC; set `GOMEMLIMIT=600MiB` (soft limit, the runtime trades CPU for memory) or `GOGC=50` when the host is tight on RAM. Neither changes the snapshot format.
+
 ## Security and privacy
 
 The index is local: no network calls, no telemetry, no uploads. The snapshot contains file names and paths, so treat the state directory as private data and exclude it from backups if that matters to you. The plugin never modifies, moves or deletes indexed files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-locator",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Whole-disk, millisecond file search for DeepSeek Harness without Everything: a self-built cross-platform index, an Everything-style query language, agent tools and a Web search panel (Ctrl+Shift+F). Windows, macOS and Linux.",
   "author": "PerryLink contributors",
   "repository": {