dsh-locator 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.5.2 — 2026-11-10
+
+* Replaced both README screenshots with demo data (`/tmp/demo`); the previous images exposed a home-directory path and have been withdrawn (npm 0.5.1 unpublished, tag/history rewritten).
+* No code change.
+
+## 0.5.1 — 2026-11-10
+
+* README is now Chinese-primary (`README.md`) with full English (`README.en.md`), Spanish, Portuguese and Hindi translations; the old `README-zh.md` was replaced.
+* Added a real panel screenshot (zh/en) and an architecture SVG under `docs/assets/`.
+* Added the same centered header, install-channel matrix, mirror badges, official-repository note and star CTA used by the rest of the family.
+
 ## 0.5.0 — 2026-11-09
 
 * **USN restart catch-up**: index records carry the NTFS FRN (in the old snapshot padding, so v1 snapshots still load), `scan --usn` persists `usn-state.json` (journal id, next USN, roots), and `serve --usn` replays the journal before serving. A file created while the daemon is stopped is found after restart without a full scan; a wrapped/mismatched journal falls back to the portable watcher. Validated on a Windows CI runner.

package/README-es.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+# 🔎 dsh-locator
+
+**Búsqueda de archivos en todo el disco, en milisegundos, para DeepSeek Harness — sin Everything.**
+
+Índice propio multiplataforma (Windows USN/MFT · macOS FSEvents · Linux inotify), cuatro herramientas para el agente y un panel web ordenable.
+
+[![npm version](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
+[![npm downloads](https://img.shields.io/npm/dm/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)
+[![version](https://img.shields.io/github/v/tag/PerryLink/dsh-locator?label=version)](https://github.com/PerryLink/dsh-locator/releases)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-locator)
+[![GitCode](https://img.shields.io/badge/GitCode-mirror-1f6feb)](https://gitcode.com/PerryLink/dsh-locator)
+
+[简体中文](README.md) · [English](README.en.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
+
+```sh
+dsh plugin --profile web add dsh-locator
+```
+
+</div>
+
+> **Repositorio oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator). Gitee y GitCode son espejos sincronizados automáticamente; GitHub es la fuente de verdad.
+>
+> Forma parte de la [familia de plugins DSH](https://github.com/PerryLink) (Apache-2.0). Si te sirve, **una ⭐ ayuda a que la próxima persona lo encuentre**; no desbloquea nada.
+
+`dsh-locator` indexa una vez los directorios que elijas, guarda el resultado en una instantánea compacta, aplica los cambios del sistema de archivos y responde consultas de nombre/ruta en decenas de milisegundos sobre más de un millón de entradas. El agente recibe `locator_search`, `locator_status`, `locator_rebuild` y `locator_export`; las personas tienen un **panel global** en la Web GUI (`Ctrl+Shift+F` o la lupa del pie de la barra lateral).
+
+## ¿Por qué otro buscador?
+
+`glob` y `grep` recorren el workspace en cada llamada: rápidos si conoces el directorio, lentos si solo recuerdas parte de un nombre. Everything es excelente en Windows, pero solo existe en Windows; envolverlo deja fuera macOS, Linux, WSL y hosts remotos. `dsh-locator` es dueño del índice, así que las mismas herramientas funcionan en cualquier sitio donde corran Node y Go.
+
+## Instalación
+
+```sh
+# npm (recomendado)
+dsh plugin --profile web add dsh-locator
+
+# GitHub main
+dsh plugin --profile web add github:PerryLink/dsh-locator
+
+# desde el código
+pnpm install
+pnpm build
+pnpm build:engine
+dsh plugin --profile web add /ruta/absoluta/dsh-locator
+
+# tarball
+npm pack
+dsh plugin --profile web add /ruta/absoluta/dsh-locator-0.5.0.tgz
+```
+
+El paquete npm incluye motores precompilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` y `darwin-arm64`.
+
+Si instalas en un perfil Web ya en ejecución, **recarga la página** (`F5`): las herramientas pueden montarse en caliente, pero el panel (`client.js`) se carga desde el boot graph al abrir la página. Los perfiles headless/TUI no montan panel.
+
+## Panel web
+
+![Panel de búsqueda de dsh-locator: resultados Markdown filtrados por ruta, con recuento, tiempo y columnas ordenables](docs/assets/panel-en.png)
+
+Pulsa `Ctrl+Shift+F` en cualquier parte de la Web GUI, o haz clic en la lupa del pie de la barra lateral. El panel consulta el mismo índice mediante rutas del host del mismo origen (`POST /dsh-locator/search`, `POST /dsh-locator/status`), sin segundo servidor ni puerto extra.
+
+* Consulta vacía: entradas recientes por fecha; al escribir, debounce de 110 ms y la misma sintaxis que las herramientas.
+* Clic en una columna para ordenar por nombre, tamaño, fecha o ruta; otro clic invierte.
+* `Solo archivos` / `Solo carpetas`; la barra inferior muestra aciertos, límite y tiempo.
+* `↑`/`↓` selecciona, `Enter` copia, `Ctrl+O` abre, `Ctrl+Enter` inserta `@"ruta"` en el compositor, doble clic revela en el explorador, `Esc` cierra.
+* La interfaz sigue `navigator.language` (zh/en/es/pt/hi).
+
+## Herramientas
+
+| Herramienta | Uso |
+|---|---|
+| `locator_search` | Consulta el índice con sintaxis estilo Everything. |
+| `locator_status` | Raíces, entradas, watcher, modo USN y errores. |
+| `locator_rebuild` | Reconstruye en segundo plano; las búsquedas siguen usando el índice anterior. |
+| `locator_export` | Copia de solo lectura en SQLite (`entries(path, name, dir, size, mtime_ms, ext)`). |
+
+### Sintaxis de consulta
+
+```text
+reporte                  palabras AND en el nombre
+"dos palabras"           frase literal
+*.go  ?                  comodines
+ext:pdf,docx  ext:!tmp   por extensión (o negación)
+path:src                 subcadena de la ruta completa
+size:>10mb  1kb..2mb     tamaño
+dm:today  dm:thisweek    fecha de modificación
+folder:  file:           solo carpetas / solo archivos
+!tmp                     negar
+case:1  wholeword:1      mayúsculas / palabra completa
+```
+
+## Configuración esencial
+
+| Clave | Valor |
+|---|---|
+| `roots` | Directorios a indexar; vacío = directorio personal. |
+| `excludes` | Globs por nombre (`node_modules`, `.git`, …). |
+| `watch` | Activa las notificaciones del sistema. |
+| `refreshIntervalMs` | Reconstrucción periódica si no hay watcher nativo. |
+| `windowsUsn` | Ruta rápida USN/MFT (Windows, administrador; por defecto `false`). |
+| `scanWorkers` | Lectores de directorio en paralelo; 0 = CPU. |
+| `stateDir` | Directorio de la instantánea; vacío = caché del sistema. |
+
+## Plataformas
+
+| Plataforma | Exploración | Actualizaciones |
+|---|---|---|
+| Linux | recorrido paralelo | inotify recursivo |
+| Windows | recorrido o USN/MFT (admin) | `ReadDirectoryChangesW`; USN reanuda tras reinicio |
+| macOS | recorrido | FSEvents en binarios cgo; kqueue como respaldo |
+
+En Windows, `scan --usn` guarda `usn-state.json` (id del diario, siguiente USN, raíces) y `serve --usn` reproduce el diario antes de servir: un archivo creado con el daemon detenido aparece al reiniciar sin reescanear. Un diario desactualizado o desmontado cae al watcher portátil.
+
+## Rendimiento
+
+- 1,2 M de entradas: consulta en caliente 25–35 ms; búsqueda durante el escaneo ~2 ms.
+- `C:\Windows` (164 216 entradas) indexado por USN en 7,8 s en un runner de CI; consulta 9,6 ms.
+- `locator_export` de 1,24 M de filas: 477 MB, 6,4 s.
+
+## Diseño
+
+![Arquitectura de dsh-locator: sistemas de archivos → escaneo/vigilancia → instantánea compacta → motor de consulta → herramientas / panel](docs/assets/architecture.svg)
+
+* **Escaneo paralelo**: cola acotada, lotes por directorio para que el padre exista antes que los hijos.
+* **Memoria**: registros de 40 B, nombres en una arena compartida, tabla de rutas abierta; la ruta completa se reconstruye solo al devolver resultados.
+* **Consulta**: los términos se compilan una vez, se reparten por fragmentos y un heap acotado selecciona `offset+limit`.
+* **Persistencia**: archivo temporal + rename atómico; el snapshot es la fuente de arranque.
+* **Protocolo**: NDJSON por stdio; sin puerto ni superficie de red.
+
+## Compilar desde el código
+
+Requiere Node `^22.19 || >=24.9`, pnpm y Go 1.22+.
+
+```sh
+pnpm install
+pnpm build
+pnpm build:engine:all
+pnpm check
+```
+
+El motor Go vive en `engine/`; pruebas: `cd engine && go test ./...`.
+
+## Límites
+
+* Solo nombres, rutas, tamaños y fechas: **no indexa contenido**. Para contenido usa `grep`.
+* No es un driver de sistema de archivos; cubre solo las raíces configuradas.
+* inotify consume un descriptor por directorio; árboles enormes pueden agotar el límite del kernel (se avisa y la instantánea sigue usable).
+* Escrituras WSL en `/mnt/c` pueden no generar notificaciones de Windows; reconstruye esas raíces.
+* macOS: FSEvents en los binarios publicados; kqueue (máx. 4.096 directorios) en compilaciones `CGO_ENABLED=0`. Los cambios de contenido dependen de la reconstrucción periódica.
+
+## Seguridad y privacidad
+
+El índice es local: sin red, sin telemetría, sin subidas. La instantánea contiene nombres y rutas; trátala como datos privados. El plugin nunca modifica, mueve ni borra los archivos indexados.
+
+## Licencia
+
+Apache-2.0.

package/README-hi.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+# 🔎 dsh-locator
+
+**DeepSeek Harness के लिए पूरे डिस्क पर मिलीसेकंड में फ़ाइल खोज — Everything के बिना।**
+
+अपना क्रॉस-प्लेटफ़ॉर्म इंडेक्स (Windows USN/MFT · macOS FSEvents · Linux inotify), एजेंट के लिए चार टूल और क्रमबद्ध करने योग्य Web पैनल।
+
+[![npm version](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
+[![npm downloads](https://img.shields.io/npm/dm/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)
+[![version](https://img.shields.io/github/v/tag/PerryLink/dsh-locator?label=version)](https://github.com/PerryLink/dsh-locator/releases)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-locator)
+[![GitCode](https://img.shields.io/badge/GitCode-mirror-1f6feb)](https://gitcode.com/PerryLink/dsh-locator)
+
+[简体中文](README.md) · [English](README.en.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
+
+```sh
+dsh plugin --profile web add dsh-locator
+```
+
+</div>
+
+> **आधिकारिक रिपॉज़िटरी:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator)। Gitee और GitCode स्वतः सिंक होने वाले मिरर हैं; GitHub ही स्रोत है।
+>
+> यह [DSH प्लगइन परिवार](https://github.com/PerryLink) (Apache-2.0) का हिस्सा है। अगर यह मदद करे, तो **एक ⭐** अगली बार खोजने वाले की मदद करता है — इससे कोई सुविधा नहीं खुलती।
+
+`dsh-locator` आपके चुने हुए डायरेक्टरी को एक बार इंडेक्स करता है, परिणाम को एक कॉम्पैक्ट स्नैपशॉट में रखता है, फ़ाइल सिस्टम के बदलाव लागू करता है, और दस लाख से अधिक प्रविष्टियों पर नाम/पथ क्वेरी कुछ दसियों मिलीसेकंड में लौटाता है। एजेंट को `locator_search`, `locator_status`, `locator_rebuild` और `locator_export` मिलते हैं; लोगों को Web GUI में एक **वैश्विक पैनल** मिलता है (`Ctrl+Shift+F` या साइडबार के निचले हिस्से में आवर्धक चिह्न)।
+
+## एक और खोज क्यों?
+
+`glob` और `grep` हर कॉल पर वर्कस्पेस घूमते हैं — डायरेक्टरी पता हो तो तेज़, नाम का कुछ हिस्सा याद हो तो धीमे। Everything Windows पर बहुत अच्छा है, पर केवल Windows पर; उसे लपेटने से macOS, Linux, WSL और रिमोट होस्ट बाहर रह जाते हैं। `dsh-locator` खुद इंडेक्स का मालिक है, इसलिए वही टूल हर जगह चलते हैं जहाँ Node और Go चलते हैं।
+
+## इंस्टॉल
+
+```sh
+# npm (अनुशंसित)
+dsh plugin --profile web add dsh-locator
+
+# GitHub main
+dsh plugin --profile web add github:PerryLink/dsh-locator
+
+# सोर्स से
+pnpm install
+pnpm build
+pnpm build:engine
+dsh plugin --profile web add /absolute/path/dsh-locator
+
+# tarball
+npm pack
+dsh plugin --profile web add /absolute/path/dsh-locator-0.5.0.tgz
+```
+
+npm पैकेज में `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` और `darwin-arm64` के पहले से बने इंजन हैं।
+
+चल रहे Web प्रोफ़ाइल में इंस्टॉल के बाद **पेज रीलोड करें** (`F5`): टूल तुरंत माउंट हो सकते हैं, पर पैनल (`client.js`) पेज लोड पर boot graph से आता है। headless/TUI प्रोफ़ाइल में पैनल नहीं मिलता।
+
+## Web पैनल
+
+![dsh-locator खोज पैनल: पथ से फ़िल्टर किए गए Markdown परिणाम, हिट संख्या, समय और क्रमबद्ध कॉलम](docs/assets/panel-en.png)
+
+Web GUI में कहीं भी `Ctrl+Shift+F` दबाएँ, या साइडबार के निचले हिस्से में आवर्धक चिह्न पर क्लिक करें। पैनल उसी इंडेक्स को समान-मूल होस्ट रूट से क्वेरी करता है (`POST /dsh-locator/search`, `POST /dsh-locator/status`) — दूसरा सर्वर या अतिरिक्त पोर्ट नहीं।
+
+* खाली क्वेरी: तारीख़ के अनुसार हाल की प्रविष्टियाँ; टाइप करते ही 110 ms डिबाउंस और टूल जैसी ही सिंटैक्स।
+* कॉलम हेडर पर क्लिक करके नाम, आकार, तारीख़ या पथ से क्रम; दोबारा क्लिक पर उलटा।
+* `केवल फ़ाइलें` / `केवल फ़ोल्डर`; निचली पट्टी में हिट, सीमा और समय।
+* `↑`/`↓` चयन, `Enter` कॉपी, `Ctrl+O` खोलें, `Ctrl+Enter` कंपोज़र में `@"पथ"` डालें, डबल-क्लिक फ़ाइल मैनेजर में दिखाएँ, `Esc` बंद।
+* इंटरफ़ेस `navigator.language` का पालन करता है (zh/en/es/pt/hi)।
+
+## टूल
+
+| टूल | काम |
+|---|---|
+| `locator_search` | Everything-शैली सिंटैक्स से इंडेक्स क्वेरी। |
+| `locator_status` | रूट, प्रविष्टियाँ, watcher, USN मोड और त्रुटियाँ। |
+| `locator_rebuild` | पृष्ठभूमि में पुनर्निर्माण; खोज पुराने इंडेक्स से चलती रहती है। |
+| `locator_export` | केवल-पढ़ने योग्य SQLite प्रति (`entries(path, name, dir, size, mtime_ms, ext)`)। |
+
+### क्वेरी सिंटैक्स
+
+```text
+report                   नाम में AND शब्द
+"do shabd"               सटीक वाक्यांश
+*.go  ?                  वाइल्डकार्ड
+ext:pdf,docx  ext:!tmp   एक्सटेंशन (या नकार)
+path:src                 पूरे पथ का उपभाग
+size:>10mb  1kb..2mb     आकार
+dm:today  dm:thisweek    बदलाव की तारीख़
+folder:  file:           केवल फ़ोल्डर / केवल फ़ाइलें
+!tmp                     नकार
+case:1  wholeword:1      केस / पूरा शब्द
+```
+
+## मुख्य कॉन्फ़िग
+
+| कुंजी | अर्थ |
+|---|---|
+| `roots` | इंडेक्स करने वाली डायरेक्टरियाँ; खाली = होम डायरेक्टरी। |
+| `excludes` | नाम-आधारित glob (`node_modules`, `.git`, …)। |
+| `watch` | सिस्टम की फ़ाइल सूचनाएँ चालू करें। |
+| `refreshIntervalMs` | नेटिव watcher न होने पर समय-समय पर पुनर्निर्माण। |
+| `windowsUsn` | USN/MFT तेज़ रास्ता (Windows, व्यवस्थापक; डिफ़ॉल्ट `false`)। |
+| `scanWorkers` | समानांतर डायरेक्टरी रीडर; 0 = CPU। |
+| `stateDir` | स्नैपशॉट डायरेक्टरी; खाली = सिस्टम कैश। |
+
+## प्लेटफ़ॉर्म
+
+| प्लेटफ़ॉर्म | स्कैन | अपडेट |
+|---|---|---|
+| Linux | समानांतर वॉक | inotify (पुनरावर्ती) |
+| Windows | वॉक या USN/MFT (admin) | `ReadDirectoryChangesW`; USN पुनः आरंभ पर फिर शुरू |
+| macOS | वॉक | cgo बाइनरी में FSEvents; `CGO_ENABLED=0` पर kqueue |
+
+Windows पर `scan --usn` `usn-state.json` (जर्नल id, अगला USN, रूट) लिखता है और `serve --usn` सेवा से पहले जर्नल दोहराता है: डेमॉन बंद रहते बनाई फ़ाइल पुनः आरंभ पर बिना पूरे स्कैन के दिखती है। पुराना/हटाया जर्नल पोर्टेबल watcher पर लौट आता है।
+
+## प्रदर्शन
+
+- 1.2 M प्रविष्टियाँ: गरम क्वेरी 25–35 ms; स्कैन के दौरान खोज ~2 ms।
+- `C:\Windows` (164,216 प्रविष्टियाँ) USN से CI runner पर 7.8 s में इंडेक्स; क्वेरी 9.6 ms।
+- 1.24 M पंक्तियों का `locator_export`: 477 MB, 6.4 s।
+
+## डिज़ाइन
+
+![dsh-locator आर्किटेक्चर: फ़ाइल सिस्टम → स्कैन/वॉच → कॉम्पैक्ट स्नैपशॉट → क्वेरी इंजन → टूल / Web पैनल](docs/assets/architecture.svg)
+
+* **समानांतर स्कैन**: सीमित कतार, प्रति-डायरेक्टरी बैच ताकि पिता बच्चों से पहले मौजूद हो।
+* **मेमोरी**: 40 B रिकॉर्ड, साझा नाम arena, खुली पथ तालिका; पूरा पथ केवल परिणाम लौटाते समय बनता है।
+* **क्वेरी**: शब्द एक बार पार्स, खंडों में समानांतर मिलान, सीमित heap से `offset+limit`।
+* **स्थायित्व**: अस्थायी फ़ाइल + atomic rename; स्नैपशॉट ही शुरुआत का स्रोत।
+* **प्रोटोकॉल**: stdio पर NDJSON; कोई पोर्ट या नेटवर्क सतह नहीं।
+
+## सोर्स से बिल्ड
+
+Node `^22.19 || >=24.9`, pnpm और Go 1.22+ चाहिए।
+
+```sh
+pnpm install
+pnpm build
+pnpm build:engine:all
+pnpm check
+```
+
+Go इंजन `engine/` में है; टेस्ट: `cd engine && go test ./...`.
+
+## सीमाएँ
+
+* केवल नाम, पथ, आकार और तारीख़: **सामग्री इंडेक्स नहीं**। सामग्री के लिए `grep`।
+* यह फ़ाइल-सिस्टम ड्राइवर नहीं; केवल कॉन्फ़िगर किए रूट कवर करता है।
+* inotify प्रति डायरेक्टरी एक descriptor लेता है; बहुत बड़े पेड़ कर्नेल सीमा पार कर सकते हैं (चेतावनी मिलती है, स्नैपशॉट उपयोगी रहता है)।
+* WSL की `/mnt/c` लेख Windows सूचनाएँ नहीं दे सकतीं; उन रूट को फिर से बनाएँ।
+* macOS: प्रकाशित बाइनरी में FSEvents; `CGO_ENABLED=0` बिल्ड में kqueue (अधिकतम 4,096 डायरेक्टरी)। सामग्री बदलाव समय-समय पर पुनर्निर्माण से।
+
+## सुरक्षा और गोपनीयता
+
+इंडेक्स स्थानीय है: कोई नेटवर्क, टेलीमेट्री या अपलोड नहीं। स्नैपशॉट में नाम और पथ हैं, इसे निजी डेटा मानें। प्लगइन इंडेक्स की गई फ़ाइलों को कभी बदलता, हटाता या स्थानांतरित नहीं करता।
+
+## लाइसेंस
+
+Apache-2.0.

package/README-pt.md

@@ -0,0 +1,162 @@
+<div align="center">
+
+# 🔎 dsh-locator
+
+**Busca de arquivos em todo o disco, em milissegundos, para o DeepSeek Harness — sem o Everything.**
+
+Índice próprio multiplataforma (Windows USN/MFT · macOS FSEvents · Linux inotify), quatro ferramentas para o agente e um painel web ordenável.
+
+[![npm version](https://img.shields.io/npm/v/dsh-locator)](https://www.npmjs.com/package/dsh-locator)
+[![npm downloads](https://img.shields.io/npm/dm/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)
+[![version](https://img.shields.io/github/v/tag/PerryLink/dsh-locator?label=version)](https://github.com/PerryLink/dsh-locator/releases)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-locator)
+[![GitCode](https://img.shields.io/badge/GitCode-mirror-1f6feb)](https://gitcode.com/PerryLink/dsh-locator)
+
+[简体中文](README.md) · [English](README.en.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
+
+```sh
+dsh plugin --profile web add dsh-locator
+```
+
+</div>
+
+> **Repositório oficial:** [GitHub `PerryLink/dsh-locator`](https://github.com/PerryLink/dsh-locator). Gitee e GitCode são espelhos sincronizados automaticamente; o GitHub é a fonte da verdade.
+>
+> Faz parte da [família de plugins DSH](https://github.com/PerryLink) (Apache-2.0). Se ajudar, **uma ⭐ ajuda a próxima pessoa a encontrar**; nada é liberado por isso.
+
+`dsh-locator` indexa uma vez os diretórios escolhidos, guarda o resultado num instantâneo compacto, aplica as mudanças do sistema de arquivos e responde consultas de nome/caminho em dezenas de milissegundos sobre mais de um milhão de entradas. O agente recebe `locator_search`, `locator_status`, `locator_rebuild` e `locator_export`; as pessoas têm um **painel global** na Web GUI (`Ctrl+Shift+F` ou a lupa no rodapé da barra lateral).
+
+## Por que outro buscador?
+
+`glob` e `grep` percorrem o workspace a cada chamada: rápidos quando você sabe o diretório, lentos quando lembra só parte de um nome. O Everything é excelente no Windows, mas só existe no Windows; envolvê-lo deixa macOS, Linux, WSL e hosts remotos de fora. O `dsh-locator` é dono do índice, então as mesmas ferramentas funcionam onde Node e Go rodam.
+
+## Instalação
+
+```sh
+# npm (recomendado)
+dsh plugin --profile web add dsh-locator
+
+# GitHub main
+dsh plugin --profile web add github:PerryLink/dsh-locator
+
+# do código
+pnpm install
+pnpm build
+pnpm build:engine
+dsh plugin --profile web add /caminho/absoluto/dsh-locator
+
+# tarball
+npm pack
+dsh plugin --profile web add /caminho/absoluto/dsh-locator-0.5.0.tgz
+```
+
+O pacote npm inclui motores pré-compilados para `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`, `darwin-x64` e `darwin-arm64`.
+
+Ao instalar num perfil Web já em execução, **recarregue a página** (`F5`): as ferramentas podem montar a quente, mas o painel (`client.js`) vem do boot graph no carregamento. Perfis headless/TUI não montam painel.
+
+## Painel web
+
+![Painel de busca do dsh-locator: resultados Markdown filtrados por caminho, com contagem, tempo e colunas ordenáveis](docs/assets/panel-en.png)
+
+Pressione `Ctrl+Shift+F` em qualquer lugar da Web GUI, ou clique na lupa no rodapé da barra lateral. O painel consulta o mesmo índice por rotas do host na mesma origem (`POST /dsh-locator/search`, `POST /dsh-locator/status`), sem segundo servidor e sem porta extra.
+
+* Consulta vazia: entradas recentes por data; ao digitar, debounce de 110 ms e a mesma sintaxe das ferramentas.
+* Clique no cabeçalho para ordenar por nome, tamanho, data ou caminho; outro clique inverte.
+* `Somente arquivos` / `Somente pastas`; o rodapé mostra resultados, limite e tempo.
+* `↑`/`↓` seleciona, `Enter` copia, `Ctrl+O` abre, `Ctrl+Enter` insere `@"caminho"` no compositor, clique duplo revela no gerenciador, `Esc` fecha.
+* A interface segue `navigator.language` (zh/en/es/pt/hi).
+
+## Ferramentas
+
+| Ferramenta | Uso |
+|---|---|
+| `locator_search` | Consulta com sintaxe estilo Everything. |
+| `locator_status` | Raízes, entradas, watcher, modo USN e erros. |
+| `locator_rebuild` | Reconstrói em segundo plano; buscas continuam no índice antigo. |
+| `locator_export` | Cópia somente leitura em SQLite (`entries(path, name, dir, size, mtime_ms, ext)`). |
+
+### Sintaxe de consulta
+
+```text
+relatorio                palavras AND no nome
+"duas palavras"          frase literal
+*.go  ?                  curingas
+ext:pdf,docx  ext:!tmp   por extensão (ou negação)
+path:src                 subcadeia do caminho completo
+size:>10mb  1kb..2mb     tamanho
+dm:today  dm:thisweek    data de modificação
+folder:  file:           só pastas / só arquivos
+!tmp                     negar
+case:1  wholeword:1      maiúsculas / palavra inteira
+```
+
+## Configuração essencial
+
+| Chave | Valor |
+|---|---|
+| `roots` | Diretórios indexados; vazio = diretório pessoal. |
+| `excludes` | Globs por nome (`node_modules`, `.git`, …). |
+| `watch` | Ativa notificações do sistema. |
+| `refreshIntervalMs` | Reconstrução periódica quando não há watcher nativo. |
+| `windowsUsn` | Caminho rápido USN/MFT (Windows, administrador; padrão `false`). |
+| `scanWorkers` | Leitores de diretório em paralelo; 0 = CPU. |
+| `stateDir` | Diretório do instantâneo; vazio = cache do sistema. |
+
+## Plataformas
+
+| Plataforma | Varredura | Atualizações |
+|---|---|---|
+| Linux | varredura paralela | inotify recursivo |
+| Windows | varredura ou USN/MFT (admin) | `ReadDirectoryChangesW`; USN retoma após reinício |
+| macOS | varredura | FSEvents nos binários cgo; kqueue como fallback |
+
+No Windows, `scan --usn` grava `usn-state.json` (id do diário, próximo USN, raízes) e `serve --usn` reproduz o diário antes de servir: um arquivo criado com o daemon parado aparece após reiniciar sem reescanear. Diário desatualizado ou removido cai no watcher portátil.
+
+## Desempenho
+
+- 1,2 M de entradas: consulta a quente 25–35 ms; busca durante a varredura ~2 ms.
+- `C:\Windows` (164.216 entradas) indexado por USN em 7,8 s num runner de CI; consulta 9,6 ms.
+- `locator_export` de 1,24 M de linhas: 477 MB, 6,4 s.
+
+## Design
+
+![Arquitetura do dsh-locator: sistemas de arquivos → varredura/vigilância → instantâneo compacto → motor de consulta → ferramentas / painel](docs/assets/architecture.svg)
+
+* **Varredura paralela**: fila limitada e lotes por diretório para o pai existir antes dos filhos.
+* **Memória**: registros de 40 B, nomes numa arena compartilhada, tabela de caminhos aberta; o caminho completo só é reconstruído ao devolver resultados.
+* **Consulta**: termos compilados uma vez, divididos em fragmentos e um heap limitado escolhe `offset+limit`.
+* **Persistência**: arquivo temporário + rename atômico; o instantâneo é a fonte de inicialização.
+* **Protocolo**: NDJSON por stdio; sem porta nem superfície de rede.
+
+## Compilar do código
+
+Requer Node `^22.19 || >=24.9`, pnpm e Go 1.22+.
+
+```sh
+pnpm install
+pnpm build
+pnpm build:engine:all
+pnpm check
+```
+
+O motor Go fica em `engine/`; testes: `cd engine && go test ./...`.
+
+## Limites
+
+* Só nomes, caminhos, tamanhos e datas: **não indexa conteúdo**. Para conteúdo use `grep`.
+* Não é um driver de sistema de arquivos; cobre apenas as raízes configuradas.
+* inotify usa um descritor por diretório; árvores enormes podem estourar o limite do kernel (há aviso e o instantâneo continua utilizável).
+* Escritas do WSL em `/mnt/c` podem não gerar notificações do Windows; reconstrua essas raízes.
+* macOS: FSEvents nos binários publicados; kqueue (máx. 4.096 diretórios) em builds `CGO_ENABLED=0`. Mudanças de conteúdo dependem da reconstrução periódica.
+
+## Segurança e privacidade
+
+O índice é local: sem rede, sem telemetria, sem uploads. O instantâneo contém nomes e caminhos; trate-o como dado privado. O plugin nunca modifica, move ou apaga os arquivos indexados.
+
+## Licença
+
+Apache-2.0.