dsh-graft-plugin 0.2.1 → 0.3.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Adithyan Raj
-
-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.
+MIT License
+
+Copyright (c) 2026 Adithya N Raj
+
+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,13 +1,22 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
+  <img alt="graft" src="assets/banner-light.png" width="1012">
+</picture>
+
+<br>
+
 # dsh-graft-plugin
 
+English | [中文](README.zh-CN.md)
+
 ![language](https://img.shields.io/badge/language-javascript-f7dc6f) ![style](https://img.shields.io/badge/style-vanilla-gray) ![license](https://img.shields.io/badge/license-MIT-blue) ![node](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen) ![dsh](https://img.shields.io/badge/dsh-web%20profile-orange) ![runtime](https://img.shields.io/badge/runtime-offline_%C2%B7_100%25_local-brightgreen) ![tests](https://img.shields.io/badge/tests-passing-brightgreen)
 
 A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that puts [graft](https://github.com/trailhq/Graft) — a prebuilt graph of every symbol, its `file:line` span, and who calls what — in front of both you and the model.
 
 It does four things:
 
-- **A chip in the composer** naming the graft index the current session is actually serving, whether it still matches the code, and how many tokens graft has saved in that repo.
-- **Five tools for the model** — `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map` — resolved per session, so one dsh can serve several workspaces at once.
+- **A chip in the composer** naming the graft index the current session is actually serving, whether it still matches the code, and how many tokens graft has saved in that repo. Its card carries a **Build** button — rebuild the index, or create the first one.
+- **Five tools for the model** — `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map` — resolved per session, so one dsh can serve several workspaces at once, git worktrees included, each with its own graph.
 - **`/graft`** to build or rebuild the index, and **auto-rebuild** after the model edits files.
 - **A `graft viz` button** that opens the graph in dsh's built-in right sidebar (0.1.5+), in [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) if you still run it, and in a browser tab as the last resort.
 
@@ -48,11 +57,32 @@ cd <your repo>
 graft build
 ```
 
+### In the desktop app
+
+The desktop dsh installs plugins from its own **Plugins** settings — no CLI, no profile directory:
+
+1. Open **Plugins** (settings, left sidebar) and click **Add plugin**.
+2. Paste the GitHub repository address into the field (the package name `dsh-graft-plugin` works too):
+
+   ```
+   https://github.com/adithyanraj03/dsh-graft-plugin
+   ```
+
+3. Click **Install**.
+
+![The Add plugin dialog with the repository address](assets/dsh-desktop-app-install.png)
+
+The dialog switches to the **Installed** confirmation, and the plugin appears under **Installed** at the bottom of the settings page:
+
+![The Installed confirmation with the install details](assets/dsh-desktop-app-install-2.png)
+
+> The dialog notes that installed plugins **do not update automatically yet** — to upgrade, uninstall and install again. The graft CLI requirement (`npm install -g @nanonets/graft`) is the same.
+
 ### The sidebar tab
 
 On dsh `0.1.5` and later the button opens the graph in **dsh's own right sidebar** — a tab titled Graft, also listed on the sidebar's guide page as "The graft graph for this workspace" — and a second click focuses the tab that is already open. No install needed for that path: the registration is soft, so an older dsh without the right sidebar falls through to `dsh-better-sidebar` when it is mounted, and to a browser tab when neither is there.
 
-If your profile still runs `dsh-better-sidebar`, that path is tried **first** and behaves exactly as before. It ships as a dependency of this plugin (0.18.x), so it is already downloaded — but dsh only mounts what the profile lists:
+If your profile still runs `dsh-better-sidebar`, that path is tried **first** and behaves exactly as before. From 0.3.0 it is an **optional peer dependency** — dsh no longer downloads it for you, so add it yourself when you want it (on dsh `0.1.5-rc.2` or later it cannot mount anyway, so most profiles should skip this):
 
 ```sh
 dsh plugin --profile web add dsh-better-sidebar
@@ -80,6 +110,14 @@ Hovering (or clicking) opens a card with the resolved root, node and edge counts
 
 ![The chip in the composer, with its hover card](assets/chip.png)
 
+The card's header carries a **Build** button beside the status pill. In a repo that already has an index it runs the same rebuild the auto-rebuild runs — graft's own sync — and holds "Building…" until the pill reads *in sync*, giving up after two minutes and showing the reason. In a workspace with no index yet, Build first asks in dsh's own dialog ("Build graft index?" — Cancel / Build index; Cancel, Escape or clicking outside builds nothing), then runs a plain offline `graft build`, which writes a `graft/` directory there.
+
+While a `graft_*` tool is running, the chip's dot blinks violet.
+
+Chip, card and viz tab are painted with dsh's own `--dsw-*` theme variables, so they follow the active theme — including theme plugins.
+
+A linked git worktree gets its own graph, never the main checkout's: the card and the viz bar name the main checkout it belongs to (`git worktree of <repo>`). With no graph yet, `/graft` in the worktree seeds the first one from it.
+
 The root is resolved from **the session's own workspace**, not from wherever dsh was launched. That is the whole reason this exists rather than the `graft mcp` server: `graft mcp` resolves its repo once, from its own working directory at startup, and nothing can re-point it afterwards. Launched from a home directory it answers *"no graph found"* for every workspace you open.
 
 ### The visualiser
@@ -125,20 +163,22 @@ All optional, all on the plugin's row in your profile's `cordis.patch.yml`:
     cwd: 'C:/path/to/repo'   # pin to one repo instead of resolving per session
     tools: false             # drop the graft_* tools, keep the chip
     command: false           # drop /graft
-    promptSection: false     # stop telling the model to prefer graft
-    autoBuild: false         # stop rebuilding after edits
+    promptSection: false     # stop telling the model to use graft
+    autoBuild: false         # stop rebuilding after edits (the card's Build button still works)
 ```
 
 ## Requirements
 
 | dsh | status |
 |---|---|
+| `0.2.1-rc.2` | test suites pass against the `0.2.1-rc.2` packages — chip, tools, `/graft`, auto-rebuild and the model-facing guidance; the dual-shape codecs load on both 0.1 and 0.2 hosts |
+| `0.1.7-rc.2` | tested on a live profile (0.3.0) — chip, tools, `/graft`, auto-rebuild and the model-facing guidance all verified |
 | `0.1.2-rc.1` – `0.1.0-rc.7` | tested, full feature set — the `graft viz` tab via `dsh-better-sidebar` |
 | `0.1.5-rc.2` / `0.1.5` | tested — chip, tools, `/graft` and auto-rebuild all work; on `0.1.5` the `graft viz` button opens the graph in the built-in right sidebar |
 | `0.2.0-rc.2` | needs plugin `0.2.1`+ — earlier releases fail to activate (see Troubleshooting) |
 
 - Node 22+
-- the `graft` CLI on PATH (`npm install -g @nanonets/graft`)
+- the `graft` CLI on PATH (`npm install -g @nanonets/graft`). A bun global install (`bun add -g @nanonets/graft`) is detected too, via `$BUN_INSTALL` or `~/.bun`.
 
 The client bundle requires only `react`, which is why it survives the dsh `0.1.5-rc.2` client-package removals that broke several neighbouring plugins.
 

package/README.zh-CN.md

@@ -0,0 +1,218 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.png">
+  <img alt="graft" src="assets/banner-light.png" width="1012">
+</picture>
+
+<br>
+
+# dsh-graft-plugin
+
+[English](README.md) | 中文
+
+![language](https://img.shields.io/badge/language-javascript-f7dc6f) ![style](https://img.shields.io/badge/style-vanilla-gray) ![license](https://img.shields.io/badge/license-MIT-blue) ![node](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen) ![dsh](https://img.shields.io/badge/dsh-web%20profile-orange) ![runtime](https://img.shields.io/badge/runtime-offline_%C2%B7_100%25_local-brightgreen) ![tests](https://img.shields.io/badge/tests-passing-brightgreen)
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，把 [graft](https://github.com/trailhq/Graft)——一张预先构建的符号图（每个符号的 `file:line` 位置、谁调用了谁）——同时摆到你和模型面前。
+
+它做四件事：
+
+- **输入框里的徽章（chip）**：说出当前会话实际在用哪个 graft 索引、它是否还与代码一致、这个仓库里 graft 已经省了多少 token。徽章的卡片上有一个 **Build** 按钮——重建索引，或者创建第一个索引。
+- **给模型五个工具** — `graft_ask`、`graft_grep`、`graft_callers`、`graft_skeleton`、`graft_map`——按会话解析，所以一个 dsh 可以同时服务多个工作区，git worktree 也不例外，每个都有自己的图。
+- **`/graft`** 构建或重建索引，模型改完文件后**自动重建**。
+- **`graft viz` 按钮**：在 dsh 内置的右侧边栏（0.1.5+）打开图；如果你还在用 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar)，就在那里打开；两者都没有时退到浏览器标签页。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-graft-plugin
+dsh --profile web
+```
+
+**pnpm 10 及以后会默认拦截未批准包的 `postinstall` 脚本**，而只要安装以非零退出，dsh 就会跳过写入插件的 bundle 行——依赖装上了，插件却隐形，dsh 还启动得干干净净，没有任何可搜索的报错。如果 `add` 以 `ERR_PNPM_IGNORED_BUILDS` 结尾，先批准再重跑：
+
+```sh
+cd ~/.dsh/profiles/web && pnpm approve-builds      # 勾选 dsh-graft-plugin
+dsh plugin --profile web add dsh-graft-plugin      # 重跑，让 bundle 行写入
+```
+
+确认它挂载了——插件必须同时出现在 profile 的 `package.json` 的 `dependencies` 和 `dsh.profile.bundles` 里：
+
+```sh
+cd ~/.dsh/profiles/web && node -e "const p=require('./package.json');
+  console.log(p.dependencies['dsh-graft-plugin'],
+              p.dsh.profile.bundles.includes('dsh-graft-plugin'))"
+```
+
+这里的每个工具都要调用 `graft` CLI，所以 PATH 上必须有 `@nanonets/graft`：
+
+```sh
+npm install -g @nanonets/graft
+```
+
+`postinstall` 会在**你的包管理器愿意运行生命周期脚本时**替你装好——pnpm 10+ 默认拦截它们，所以在 pnpm 下请把上面这条命令当作必需步骤，而不是后备。若全局 npm 前缀需要提权，postinstall 会说明并打印那条需要手动执行的命令。
+
+然后给仓库建一次索引：
+
+```sh
+cd <your repo>
+graft build
+```
+
+### 桌面应用
+
+桌面版 dsh 从自己的 **Plugins** 设置页安装插件——不用 CLI，不用 profile 目录：
+
+1. 打开 **Plugins**（设置页左侧栏），点 **Add plugin**。
+2. 把 GitHub 仓库地址粘进输入框（包名 `dsh-graft-plugin` 也可以）：
+
+   ```
+   https://github.com/adithyanraj03/dsh-graft-plugin
+   ```
+
+3. 点 **Install**。
+
+![Add plugin 对话框与仓库地址](assets/dsh-desktop-app-install.png)
+
+对话框会切换到 **Installed** 确认页，插件同时出现在设置页底部的 **Installed** 列表里：
+
+![Installed 确认页与安装详情](assets/dsh-desktop-app-install-2.png)
+
+> 对话框也提示：已安装的插件**目前不会自动更新**——升级请先卸载再重装。graft CLI 的要求（`npm install -g @nanonets/graft`）不变。
+
+### 侧边栏标签页
+
+在 dsh `0.1.5` 及以后，这个按钮会在 **dsh 自己的右侧边栏**里打开图——一个名为 Graft 的标签页，同时列在边栏引导页里，说明是 "The graft graph for this workspace"——再次点击会聚焦已打开的标签页。这条路径不需要安装任何东西：注册是软性的，所以没有右侧边栏的旧版 dsh 会退到已挂载的 `dsh-better-sidebar`，两者都没有时退到浏览器标签页。
+
+如果你的 profile 还在用 `dsh-better-sidebar`，会**优先**尝试那条路径，行为和以前完全一样。从 0.3.0 起它是**可选对等依赖（optional peer dependency）**——dsh 不再替你下载，想要就自己加（在 dsh `0.1.5-rc.2` 及以后它本来就挂不起来，多数 profile 可以跳过）：
+
+```sh
+dsh plugin --profile web add dsh-better-sidebar
+```
+
+> **兼容性。** `dsh-better-sidebar` 0.18.x 需要 `@deepseek-ai/dsh-client-ui-primitives`，而 dsh 在 `0.1.5-rc.2` 移除了它。在该版本及以后它挂不起来——那些 profile 正好由内置右侧边栏接管。本插件其余部分——徽章、工具、`/graft`、自动重建——都不受影响。
+
+徽章、工具、`/graft` 和自动重建在完全没有侧边栏时也都工作；按钮只是在两个都没有时退到浏览器标签页。
+
+> 这个插件**故意不**自己插入 `dsh-better-sidebar` 行。那个包自己的 bundle 行带一个守卫：当已有另一个启用的行挂载同一个包时，它会自我禁用。第二条不同 id 的行会让这个守卫变成循环判断，输掉的那一边是*你现有的边栏悄悄自我禁用*。一条显式命令比这个风险值钱。
+
+## 你会得到什么
+
+### 徽章
+
+待在输入框里模型名的旁边：
+
+```
+● graft · my-repo          in sync
+◐ graft · my-repo          syncing
+▲ graft · my-repo          stale
+```
+
+悬停（或点击）打开一张卡片：解析出的根目录、节点与边数、新鲜度、累计省下的 token，以及 `graft viz` 按钮。
+
+![输入框里的徽章与悬停卡片](assets/chip.png)
+
+卡片头部在状态胶囊旁边有一个 **Build** 按钮。在已有索引的仓库里，它跑的就是自动重建用的那套同步——graft 自己的 sync——并停在 "Building…" 直到胶囊显示 *in sync*，两分钟后放弃并给出原因。在还没有索引的工作区里，Build 会先用 dsh 自己的对话框确认（"Build graft index?" — Cancel / Build index；取消、Escape 或点框外都不会构建），然后跑一次纯离线的 `graft build`，在那里写出一个 `graft/` 目录。
+
+`graft_*` 工具运行期间，徽章的圆点会闪紫色。
+
+徽章、卡片和可视化标签页全部用 dsh 自己的 `--dsw-*` 主题变量绘制，因此跟随当前主题——包括主题插件。
+
+链接的 git worktree 拥有自己的图，绝不借用主检出（main checkout）的：卡片和边栏标签条都会标出它所属的主检出（`git worktree of <repo>`）。还没有图时，在 worktree 里 `/graft` 会从主检出播种出第一张图。
+
+根目录是从**会话自己的工作区**解析的，不是从 dsh 的启动位置。这正是本插件存在、而不是用 `graft mcp` 服务器的原因：`graft mcp` 在启动时从自己的工作目录解析一次仓库，之后没有任何办法改指。从主目录启动时，它对你打开的每个工作区都回答*"no graph found"*。
+
+### 可视化
+
+`graft viz` 按钮把图作为一个标签页打开——在 `0.1.5`+ 的 dsh 内置右侧边栏里，或者在你仍在使用的 [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) 里。上下文视图铺开整张图：
+
+![边栏里的图 — 上下文视图](assets/viz-context.png)
+
+代码视图下钻到单个文件——它包含什么、依赖什么、被谁依赖：
+
+![边栏里的图 — 代码视图](assets/viz-code.png)
+
+### 工具
+
+| 工具 | 回答什么 |
+|---|---|
+| `graft_ask` | "X 是怎么工作的" / "Y 在哪"——带排序的命中，代码直接内联在精确的 `file:line` |
+| `graft_grep` | 每一处出现，按所在符号分组（`graft_ask` 只给 top-N，会漏） |
+| `graft_callers` | 谁调用一个符号、它调用谁，或改名前的完整爆炸半径 |
+| `graft_skeleton` | 一个文件的完整 API，约 200 token |
+| `graft_map` | 在陌生目录树里定位方向 |
+
+它们都不接受布尔参数，而是用字符串枚举——`detail: "full"` 而不是 `full: true`——对模型更好读，也绕开了一些 OpenAI 兼容服务器上的一个真实故障：*设置*了布尔值的工具调用会被发成字面的 `<tool_call>` 文本，永远不执行。
+
+### `/graft`
+
+- `/graft` — 构建索引，已有则重建
+- `/graft status` — 把徽章知道的东西打成文字
+- `/graft deep` — 完整重建
+
+### 自动重建
+
+模型写入或编辑文件后，索引在后台重建，并做了防抖，长回合不会每次击键都重建。这里复用 graft 自己的 sync runner，而不是重新实现一遍，所以它不会和 `graft build` 的行为漂移。
+
+## 配置
+
+全部可选，全部写在 profile 的 `cordis.patch.yml` 里本插件的那一行上：
+
+```yaml
+- id: graft-status
+  name: 'dsh-graft-plugin'
+  config:
+    cwd: 'C:/path/to/repo'   # 固定到一个仓库，而不是按会话解析
+    tools: false             # 去掉 graft_* 工具，保留徽章
+    command: false           # 去掉 /graft
+    promptSection: false     # 不再告诉模型使用 graft
+    autoBuild: false         # 不再在编辑后重建（卡片上的 Build 按钮仍然可用）
+```
+
+## 系统要求
+
+| dsh | 状态 |
+|---|---|
+| `0.2.1-rc.2` | 测试套件针对 `0.2.1-rc.2` 的包全部通过——徽章、工具、`/graft`、自动重建和面向模型的指引；双形态 codec 在 0.1 和 0.2 宿主上都能加载 |
+| `0.1.7-rc.2` | 在真实 profile 上测试过（0.3.0）——徽章、工具、`/graft`、自动重建和面向模型的指引全部验证 |
+| `0.1.2-rc.1` – `0.1.0-rc.7` | 测试过，完整功能——`graft viz` 标签页经由 `dsh-better-sidebar` |
+| `0.1.5-rc.2` / `0.1.5` | 测试过——徽章、工具、`/graft`、自动重建全部工作；在 `0.1.5` 上 `graft viz` 按钮在内置右侧边栏打开图 |
+| `0.2.0-rc.2` | 需要插件 `0.2.1`+——更早的发行版无法激活（见故障排查） |
+
+- Node 22+
+- PATH 上的 `graft` CLI（`npm install -g @nanonets/graft`）。bun 的全局安装（`bun add -g @nanonets/graft`）也能被识别，经由 `$BUN_INSTALL` 或 `~/.bun`。
+
+客户端 bundle 只依赖 `react`——这就是它能在 dsh `0.1.5-rc.2` 移除一批客户端包、弄坏了好几个相邻插件的情况下存活的原因。
+
+## 开发
+
+```sh
+npm install
+npm test           # 可移植：在临时目录里构建一个合成的 graft 索引
+npm run test:live  # 用真实 graft CLI 对着真实仓库跑
+```
+
+`npm test` 不需要任何 graft 索引，机器上也不需要装 graft。唯一会真建索引的那个套件在 graft 缺失时会大声地自我跳过——缺 CLI 是一种环境状态，不是缺陷。
+
+### 两个标识符，故意不同
+
+cordis 行的 `id`（`graft-status`）是本插件自己的把手——它键控存储文件、prompt 区块和每个 effect 标签，并且在改名中保持稳定。
+
+客户端 bundle 的 `__ModuleLoader__.load({ id })` **不是**那个把手。它必须是已发布的包名：dsh 用 `entry.options.name`——即 `cordis.patch.yml` 里的 `name:`——构建每条客户端行，把 bundle 服务在 `/plugins/<name>/client.js`，然后断言有一个以同一名字注册的工厂。在那里用行 id 会让每次启动都失败：
+
+```
+bundle /plugins/dsh-graft-plugin/client.js loaded without
+registering "dsh-graft-plugin" via __ModuleLoader__.load
+```
+
+`npm test` 双向守着这一点（这个守卫随 0.1.1 的修复加入）。
+
+## 故障排查
+
+**徽章没出现，而 dsh 启动毫无报错。** 插件在 profile 的 `package.json` 的 `dependencies` 里，却不在 `dsh.profile.bundles` 里——pnpm 10+ 下 `add` 以 `ERR_PNPM_IGNORED_BUILDS` 非零退出时就是这样：dsh 跳过 bundle 行，启动看起来一切正常。修法：在 profile 目录里 `pnpm approve-builds`（勾选 `dsh-graft-plugin`），然后重跑 `dsh plugin --profile web add dsh-graft-plugin`。如果 `pnpm approve-builds` 说没有待批准的包，去 profile 的 `pnpm-workspace.yaml` 里找未回答的 `dsh-graft-plugin` 条目（pnpm 的批准占位符），先把它的值改成 `true`。
+
+**在 dsh 0.2 上插件加载失败，报 `strict codec has no create() factory`，dsh 还提议移除它。** dsh 0.2 要求每个 strict remote codec 都带一个 `create()` schema 工厂；`0.2.1` 之前的插件发行版只有 0.1 的 `schema` 键。升级到 `0.2.1` 或更新版本——它两种都带，0.1 和 0.2 上都能加载。
+
+**`/graft` 说 graft CLI 不在 PATH 上。** postinstall 被拦截或被跳过了（见安装）：`npm install -g @nanonets/graft`。
+
+## 许可证
+
+MIT

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-graft-plugin",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Shows which graft index a dsh session is serving and whether it still matches the code, and gives the model graft_ask, graft_grep, graft_callers, graft_skeleton and graft_map as native tools.",
+  "icon": "assets/icon.png",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -25,12 +26,14 @@
     "scripts/test-tools.mjs",
     "scripts/test-autosync.mjs",
     "scripts/test-command.mjs",
+    "scripts/test-guidance.mjs",
     "README.md",
     "LICENSE",
-    "screenshots.json"
+    "screenshots.json",
+    "assets/icon.png"
   ],
   "scripts": {
-    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs",
+    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs && node scripts/test-guidance.mjs",
     "test:live": "node scripts/test-tools.mjs",
     "postinstall": "node scripts/postinstall.mjs"
   },
@@ -45,15 +48,19 @@
       ]
     }
   },
-  "dependencies": {
-    "dsh-better-sidebar": "^0.18.0"
-  },
   "peerDependencies": {
-    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.6"
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.6",
+    "dsh-better-sidebar": ">=0.18.0"
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1"
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2"
   },
   "keywords": [
     "dsh-plugin",

package/scripts/test-autosync.mjs

@@ -1,4 +1,5 @@
-import { savedTokensIn } from '../src/graft-tools.js'
+import { join } from 'node:path'
+import { resolveGraftCommand, savedTokensIn } from '../src/graft-tools.js'
 import { createAutoSync } from '../src/auto-sync.js'
 import { totalSaved } from '../src/index.js'
 
@@ -76,6 +77,17 @@ console.log('\n--- graft missing is not an error ---')
 const none = createAutoSync({ graft: null, now: () => now, spawn: () => { throw new Error('should not spawn') } })
 check('no graft, no rebuild, no throw', (await none.syncIfDirty('C:/x')) === 'graft-unavailable')
 
+console.log('\n--- a manual Build forces a rebuild, like the popup button ---')
+// The popup's Build must not go through syncIfDirty's gates: a repo whose
+// stats already read clean (plain `graft build` never patches stats.json, so
+// `dirty` is whatever the last sync-run left) would answer 'clean' and spawn
+// nothing — the exact "button press changes nothing" shipped once.
+state.lock = true
+now += 60_000
+check('a forced rebuild skips the clean gate', (await sync.rebuild('C:/y')) === 'started')
+check('and it spawned graft\'s sync-run for that root', spawned.some((a) => a[1][1] === 'C:/y'), JSON.stringify(spawned.at(-1)))
+check('it set syncing so the chip can show it', state.stats.syncing === true)
+
 console.log('\n--- mid-turn rebuild: a long turn must not sit on a stale graph ---')
 // The turn boundary alone left a graph dirty for 36 minutes of one agentic
 // turn while the model kept querying it. A write now also arms a debounce.
@@ -106,6 +118,11 @@ check('a second write replaces the timer, not adds one', pendingTimers.size ===
 const fire = [...pendingTimers.values()][0]
 pendingTimers.clear()
 await fire()
+// The timer callback fires syncIfDirty without awaiting it (fire-and-forget
+// by design — a throw inside a timer must never surface), so flush before
+// asserting the spawn landed. This needed one more hop once syncIfDirty
+// started delegating to rebuild().
+await new Promise((resolve) => setTimeout(resolve, 0))
 check('the quiet period rebuilds without waiting for the turn', fired.length === 1, String(fired.length))
 
 const off = createAutoSync({ graft: { state, syncRun: 'x' }, now: () => now, spawn: () => ({ on() {}, unref() {} }), debounceMs: 0, setTimeout: () => { throw new Error('should not arm') } })
@@ -113,5 +130,53 @@ let armed = true
 try { await off.markDirty('C:/y') } catch { armed = false }
 check('debounceMs 0 restores turn-end-only', armed === true)
 
+console.log('\n--- a graft cli we cannot locate must never crash dsh ---')
+// THE ORIGINAL FATALITY: graft installed as a bare shim (bun global) left
+// `cliPath` undefined, `dirname(undefined)` in loadGraftState escaped the
+// `void`-ed markDirty as an unhandled rejection, and dsh died on the FIRST
+// successful edit in an indexed repo. These checks pin the guarantee: no
+// input, no throw, no rejection, no spawn.
+const noCli = createAutoSync({ now: () => now, spawn: (...a) => { spawned.push(a); return { on() {}, unref() {} } }, debounceMs: 0 })
+let crashed = false
+const spawnedBefore = spawned.length
+try { await noCli.markDirty('C:/no-cli') } catch { crashed = true }
+check('markDirty resolves without a cli', crashed === false)
+check('and never spawns a rebuild', spawned.length === spawnedBefore, String(spawned.length - spawnedBefore))
+check('syncIfDirty reports graft unavailable', (await noCli.syncIfDirty('C:/no-cli')) === 'graft-unavailable')
+
+// Even a loader that REJECTS is swallowed — graft() awaits the injected stub
+// inside its own try, so no input shape can turn into an unhandled rejection.
+const throwing = createAutoSync({ graft: Promise.reject(new Error('boom')), now: () => now, spawn: () => ({ on() {}, unref() {} }), debounceMs: 0 })
+crashed = false
+try { await throwing.markDirty('C:/throwing') } catch { crashed = true }
+check('a rejecting graft loader is swallowed', crashed === false)
+check('and sync stays unavailable, not fatal', (await throwing.syncIfDirty('C:/throwing')) === 'graft-unavailable')
+
+console.log('\n--- resolveGraftCommand finds graft however it was installed ---')
+const fakeExists = (set) => (p) => set.has(p)
+const bunCli = join('/home/x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')
+// A bun global install: only the shim is on PATH, the package lives under
+// $BUN_INSTALL/install/global. The PATH-only scan returned prefix: [] here,
+// which is what fed undefined into loadGraftState above.
+const viaBunInstall = resolveGraftCommand(
+  { PATH: '/home/x/.bun/bin', BUN_INSTALL: '/home/x/.bun', HOME: '/home/x' },
+  fakeExists(new Set([bunCli])),
+)
+check('a bun global install resolves to its dist cli', viaBunInstall.prefix[0] === bunCli && viaBunInstall.shell === false, viaBunInstall.prefix[0])
+const viaHome = resolveGraftCommand(
+  { PATH: '', HOME: '/home/x' },
+  fakeExists(new Set([bunCli])),
+)
+check('or via HOME/.bun when BUN_INSTALL is unset', viaHome.prefix[0] === bunCli, viaHome.prefix[0])
+const viaUserprofile = resolveGraftCommand(
+  { PATH: '', USERPROFILE: 'C:\\Users\\x' },
+  // The fixture path is built with the same join() the source uses, so this
+  // checks WHERE the lookup happens, not how a host renders separators.
+  fakeExists(new Set([join('C:\\Users\\x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js')])),
+)
+check('or via USERPROFILE/.bun on Windows', viaUserprofile.prefix[0] === join('C:\\Users\\x', '.bun', 'install', 'global', 'node_modules', '@nanonets', 'graft', 'dist', 'cli.js'), viaUserprofile.prefix[0])
+const bare = resolveGraftCommand({ PATH: '', HOME: '/home/x' }, fakeExists(new Set()))
+check('nothing installed falls back to the bare command', bare.command === 'graft' && bare.prefix.length === 0)
+
 console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
 process.exit(failures === 0 ? 0 : 1)