dsh-everything 0.0.0-stage → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.3.0] - 2026-10-26
+
+### Added
+- `countOnly`: return just the total match count in one round-trip — the
+  fastest way to check existence or estimate volume.
+- `dateCreated`: include each result's creation date.
+- ES CLI self-update: the plugin keeps its **self-installed** `es.exe`
+  current against the pinned known-good release (user-managed installs are
+  never touched).
+- Tool description now documents search syntax quirks and the NTFS/reFS
+  coverage limit (FAT/exFAT and network shares are typically not indexed).
+
+### Fixed
+- The background provisioning probe used the pre-resolution `esPath`
+  (possibly null) instead of the freshly resolved path, which could log a
+  spurious "auto-install failed" warning on auto-installed setups.
+- Backend recovery (auto-install / auto-start retry) now also covers the
+  count-only path, not just the search path.
+
+## [1.2.0] - 2026-10-26
+
+### Changed
+- Auto-install now resolves the **latest stable** version from the
+  voidtools.com downloads page instead of installing a pinned version; the
+  recorded known-good releases remain as SHA256-verified fallbacks when the
+  page is unreachable.
+- Downloads try a **direct connection first**; a configured or system proxy
+  is only a fallback, so machines without proxy tools (or with a stale
+  proxy setting) install reliably.
+
+### Added
+- Newer-than-pinned upstream releases are verified by their voidtools
+  Authenticode signature (with a raw .NET certificate-chain fallback when
+  `Get-AuthenticodeSignature`'s module fails to load).
+
+## [1.1.0] - 2026-10-26
+
+### Added
+- `autoInstall` (default on): when the backend is missing, the plugin
+  downloads the pinned ES CLI (SHA256-verified) into
+  `%LOCALAPPDATA%\dsh-everything\bin` and installs Everything via winget or
+  the official silent setup, then starts it — fresh machines need no manual
+  setup.
+- Proxy-aware downloads: `HTTPS_PROXY`/`HTTP_PROXY` or the Windows system
+  proxy, with fetch → curl.exe → PowerShell fallbacks.
+- New `installDir` config key; new `ES_SETUP_FAILED` error code.
+
+## [1.0.0] - 2026-10-26
+
+### Added
+- `everything_search` tool: whole-disk file/folder search through the local
+  Everything (voidtools) index via `es.exe -json`, with size and
+  date-modified columns.
+- Everything search syntax pass-through: `path`, `regex`, `matchCase`,
+  `wholeWord`, `foldersOnly` / `filesOnly` filters, `sort` order, and
+  `offset` pagination.
+- Exact total hit count via `-get-result-count`, fetched only when the page
+  is full (truncation possible).
+- `autoStart` (default on): launches `Everything.exe -startup` and waits for
+  IPC when the index is not running.
+- Built-in search-paths result card (`presentCall` / `presentResult`).
+- Actionable, coded errors (`ES_NOT_FOUND`, `ES_NOT_RUNNING`, `ES_TIMEOUT`,
+  `ES_ABORTED`, `ES_UNSUPPORTED_PLATFORM`, …); non-Windows platforms get a
+  stub tool that fails with a clear platform message.
+- English and Chinese plugin metadata and icon.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-everything contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# dsh-everything
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文文档](README.zh-CN.md)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that gives the agent an **`everything_search`** tool: whole-disk file and folder search in **milliseconds**, powered by the local [Everything](https://www.voidtools.com/) (voidtools) index through its official command line `es.exe`.
+
+Instead of recursively scanning directories (glob) when the model needs to locate a file, the agent asks Everything's pre-built index — instant even on drives with millions of files.
+
+## Requirements
+
+- **Windows** (Everything is a Windows-only application; on other platforms the plugin registers a stub that fails with a clear message)
+- [Everything 1.4+](https://www.voidtools.com/downloads/) and the [ES command line tool](https://www.voidtools.com/downloads/) (`es.exe`) — **installed automatically on first use** (see below)
+
+### Automatic backend setup (default)
+
+With `autoInstall: true` (the default), the plugin provisions the backend by itself when it is missing:
+
+1. Resolves the **latest stable** ES CLI from the voidtools.com downloads page, downloads the zip, and extracts `es.exe` to `%LOCALAPPDATA%\dsh-everything\bin` (per-user, no admin).
+2. Installs **Everything** via `winget install voidtools.Everything` when winget is available, otherwise downloads the latest stable official setup and runs it silently — either path may show **one UAC prompt**.
+3. Launches Everything and waits for its IPC before searching.
+
+Downloads always go **direct first** — no proxy is needed, and a stale system-proxy setting can never break the install. A proxy (`HTTPS_PROXY`/`HTTP_PROXY` env, or the Windows system proxy) is only used as a fallback. Integrity: when the resolved version matches the known-good release recorded in [`setup.js`](setup.js), the download is SHA256-verified; a newer upstream release is verified by its **voidtools Authenticode signature** instead. If the downloads page is unreachable, the recorded known-good release (SHA256-verified) is used. Installs fail closed when verification fails.
+
+The plugin also keeps its **self-installed** copy of `es.exe` current: on startup it compares the file version against the pinned known-good release and upgrades the copy it owns (user-managed installs are never touched).
+
+Set `autoInstall: false` if you prefer to install the backend yourself:
+
+```powershell
+winget install --id voidtools.Everything --silent
+Invoke-WebRequest https://www.voidtools.com/ES-1.1.0.37.x64.zip -OutFile ES.zip
+Expand-Archive ES.zip -DestinationPath "C:\Program Files\Everything" -Force
+Start-Process "C:\Program Files\Everything\Everything.exe"
+```
+
+## Installation
+
+In a DSH session, ask the agent or call the plugin manager:
+
+```
+plugin_manager install_bundle with target = this package directory (or the npm spec once published)
+```
+
+The plugin activates as `dsh-everything` and registers the `everything_search` tool for every agent in the profile.
+
+## Tool: `everything_search`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `query` *(required)* | string | Everything search expression: `report ext:docx`, `*.sln dm:thisweek`, `path:\projects\ ext:py`. Space = AND, `\|` = OR, `!` = NOT, quotes = exact phrase. |
+| `path` | string | Restrict to a directory and its subtree (absolute path). |
+| `maxResults` | integer | Result cap (default 100, ceiling 1000). |
+| `offset` | integer | Skip leading results (pagination). |
+| `sort` | string | e.g. `date-modified-descending`, `size-descending`, `name-ascending`. Keys: `name`, `path`, `size`, `extension`, `date-created`, `date-modified`, `date-accessed`, `run-count`, plus `-ascending`/`-descending`. |
+| `regex` | boolean | Treat `query` as a full-path regular expression. |
+| `matchCase` | boolean | Case-sensitive matching (default: insensitive). |
+| `wholeWord` | boolean | Match whole words only. |
+| `foldersOnly` / `filesOnly` | boolean | Restrict result type. |
+| `dateCreated` | boolean | Also return each result's creation date. |
+| `countOnly` | boolean | Return only the total match count — the fastest way to check existence or estimate volume. |
+
+Returns `{ query, total, truncated, results: [{ path, size, dateModified, dateCreated? }] }` and renders in the chat as a search-paths card.
+
+Typical queries: `report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · recently changed files with `sort: date-modified-descending` + `dm:thisweek`.
+
+> **Scope note:** searches names and paths only, never file contents — content search stays with `grep`.
+> **Coverage note:** results follow the local Everything index — NTFS/reFS drives and folders explicitly added to the index. FAT/exFAT removable drives and network shares are typically not covered.
+
+## Configuration
+
+Edit the plugin's `config` in `cordis.patch.yml` (or your profile's patch layer):
+
+| Key | Default | Description |
+|---|---|---|
+| `esPath` | auto-detect | Absolute path to `es.exe`. |
+| `everythingPath` | sibling of `esPath` | Absolute path to `Everything.exe`, used by autoStart. |
+| `autoStart` | `true` | Launch Everything and wait for its IPC when it is not running. |
+| `autoInstall` | `true` | Download & install Everything + ES CLI when missing (see above). |
+| `installDir` | `%LOCALAPPDATA%\dsh-everything` | Where the auto-installed ES CLI lives. |
+| `maxResults` | `100` | Default per-call result cap. |
+| `timeoutMs` | `8000` | Per-spawn timeout (ms). |
+
+## Privacy
+
+The search scope is **every indexed drive** on the machine, and result paths are sent to the model as tool output. Keep that in mind on machines with sensitive directory layouts; use `path` to scope searches.
+
+## Development
+
+```bash
+node --test                # unit tests (any platform)
+node --test test/integration.test.mjs   # needs a running Everything (Windows)
+```
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,95 @@
+# dsh-everything
+
+[English](README.md)
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）插件，为模型注册 **`everything_search`** 工具：借助本机 [Everything](https://www.voidtools.com/)（voidtools）索引，通过官方命令行 `es.exe` 实现**毫秒级**全盘文件/文件夹搜索。
+
+当模型需要找文件时，不再递归遍历目录（glob），而是直接查询 Everything 预先建好的索引——即使磁盘上有数百万文件也是秒回。
+
+## 环境要求
+
+- **Windows**（Everything 是 Windows 独占应用；其他平台上插件会注册一个明确报错的占位工具）
+- [Everything 1.4+](https://www.voidtools.com/zh-cn/downloads/) 与 [ES 命令行工具](https://www.voidtools.com/zh-cn/downloads/)（`es.exe`）——**缺失时插件会自动安装**（见下文）
+
+### 自动安装后端（默认）
+
+`autoInstall: true`（默认）时，插件在检测到后端缺失后会自行准备环境：
+
+1. 从 voidtools.com 下载页解析**最新稳定版** ES CLI，下载压缩包并把 `es.exe` 解压到 `%LOCALAPPDATA%\dsh-everything\bin`（用户目录，无需管理员）。
+2. 优先用 `winget install voidtools.Everything` 安装 **Everything**；没有 winget 时下载最新稳定版官方安装包静默运行——两种方式都可能弹**一次 UAC 授权框**。
+3. 启动 Everything 并等待其 IPC 就绪后才执行搜索。
+
+下载**始终直连优先**——无需任何代理工具，系统代理设置残留也不会影响安装；代理（`HTTPS_PROXY`/`HTTP_PROXY` 环境变量或 Windows 系统代理）只作为兜底。完整性校验：解析到的版本与 [`setup.js`](setup.js) 记录的已知良好版本一致时做 SHA256 校验；更新的上游版本改验 **voidtools 数字签名**；下载页不可达时回退到已知良好版本（SHA256 校验）。校验失败一律中止安装。
+
+插件还会保持**自装**的 `es.exe` 不过时：启动时会比对文件版本与插件内置的已知良好版本，落后才升级，且只升级自己装的副本（用户自装的 es.exe 永不动）。
+
+想完全自己装后端，可设 `autoInstall: false`：
+
+```powershell
+winget install --id voidtools.Everything --silent
+Invoke-WebRequest https://www.voidtools.com/ES-1.1.0.37.x64.zip -OutFile ES.zip
+Expand-Archive ES.zip -DestinationPath "C:\Program Files\Everything" -Force
+Start-Process "C:\Program Files\Everything\Everything.exe"
+```
+
+## 安装
+
+在 DSH 会话中让插件管理器安装本包目录（或发布后的 npm 包名）：
+
+```
+plugin_manager install_bundle，target = 本包目录的绝对路径
+```
+
+插件以 `dsh-everything` 激活，并为该 profile 下的所有 Agent 注册 `everything_search` 工具。
+
+## 工具：everything_search
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `query` *（必填）* | string | Everything 搜索表达式：`report ext:docx`、`*.sln dm:thisweek`、`path:\projects\ ext:py`。空格 = 与，`\|` = 或，`!` = 非，双引号 = 精确短语。 |
+| `path` | string | 限定在某目录及其子目录内（绝对路径）。 |
+| `maxResults` | integer | 返回条数上限（默认 100，封顶 1000）。 |
+| `offset` | integer | 跳过前 N 条（分页）。 |
+| `sort` | string | 排序，如 `date-modified-descending`、`size-descending`、`name-ascending`。键：`name`、`path`、`size`、`extension`、`date-created`、`date-modified`、`date-accessed`、`run-count`，可加 `-ascending`/`-descending`。 |
+| `regex` | boolean | 把 `query` 当作全路径正则表达式。 |
+| `matchCase` | boolean | 区分大小写（默认不区分）。 |
+| `wholeWord` | boolean | 整词匹配。 |
+| `foldersOnly` / `filesOnly` | boolean | 只看文件夹 / 只看文件。 |
+| `dateCreated` | boolean | 一并返回每个结果的创建时间。 |
+| `countOnly` | boolean | 只返回匹配总数——判断存在性、估量级的最快方式。 |
+
+返回 `{ query, total, truncated, results: [{ path, size, dateModified, dateCreated? }] }`，在会话里以搜索路径卡片展示。
+
+典型查询：`report ext:docx` · `*.sln dm:thisweek` · `size:>500mb` · `notes !archive` · 最近改动文件用 `sort: date-modified-descending` + `dm:thisweek`。
+
+> **范围说明**：只搜文件名和路径，不搜文件内容——内容搜索请继续用 `grep`。
+> **覆盖说明**：结果取决于本机 Everything 索引——NTFS/reFS 磁盘与显式加入索引的目录；FAT/exFAT 可移动盘与网络共享通常不在覆盖范围。
+
+## 配置
+
+在 `cordis.patch.yml`（或你 profile 的 patch 层）中修改插件 `config`：
+
+| 键 | 默认值 | 说明 |
+|---|---|---|
+| `esPath` | 自动探测 | `es.exe` 的绝对路径。 |
+| `everythingPath` | `esPath` 同目录 | `Everything.exe` 路径，供 autoStart 使用。 |
+| `autoStart` | `true` | Everything 未运行时自动启动并等待其 IPC 就绪。 |
+| `autoInstall` | `true` | 后端缺失时自动下载并安装 Everything + ES CLI（见上文）。 |
+| `installDir` | `%LOCALAPPDATA%\dsh-everything` | 自动安装的 ES CLI 存放目录。 |
+| `maxResults` | `100` | 单次返回条数默认上限。 |
+| `timeoutMs` | `8000` | 单次 spawn 超时（毫秒）。 |
+
+## 隐私
+
+搜索范围是本机**所有已索引磁盘**，结果路径会作为工具输出发给模型。在目录结构敏感的机器上请注意，可用 `path` 参数收窄范围。
+
+## 开发
+
+```bash
+node --test                # 单元测试（任意平台）
+node --test test/integration.test.mjs   # 需要运行中的 Everything（Windows）
+```
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: dsh-everything
+      name: 'dsh-everything'
+      config:
+        autoStart: true
+        autoInstall: true
+        maxResults: 100
+        timeoutMs: 8000

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="4" y="4" width="56" height="56" rx="12" fill="#2b6cb0"/>
+  <circle cx="28" cy="28" r="12" fill="none" stroke="#ffffff" stroke-width="4"/>
+  <line x1="37" y1="37" x2="48" y2="48" stroke="#ffffff" stroke-width="5" stroke-linecap="round"/>
+  <path d="M20 28h16M28 20v16" stroke="#90cdf4" stroke-width="3" stroke-linecap="round"/>
+</svg>