dsh-project-sources 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 — 2026-11-05
+
+Initial release.
+
+### Added
+
+- Codex-style project sources: attach folders to a workspace, each with an
+  editable alias; the workspace root stays the session `cwd`.
+- Sandbox re-rooting for `write` / `edit` / `pwsh` / `bash`, so every source
+  gets the session's current mode (read-only still denies, workspace-write
+  allows).
+- Project editor: session-header button + session-creation dock entry; native
+  folder chooser on Windows (PowerShell) and macOS (osascript), falling back to
+  the Host picker and then a manual path field.
+- Alias → absolute path mapping injected into the system prompt.
+- Companion `@` menu group: source folders by alias or folder name, nested
+  levels by `alias/…` or absolute path.
+- Source-folder skills: recursive discovery under `<source>/.dsh/skills`,
+  `<source>/.agents/skills` and `<source>/skills`.
+- Sessionless `projectSources/*` remote API (`get`, `set`, `listFiles`, `pick`).
+- Mock-runtime tests for the Host half (`test/smoke.mjs`, `test/skills.mjs`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YanGuoHong
+
+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/NOTICE

@@ -0,0 +1,10 @@
+dsh-project-sources
+Copyright (c) 2026 YanGuoHong
+
+This product includes a design adapted from software developed as part of
+dsh-multi-folder (https://github.com/AngelosZou/dsh-multi-folder),
+Copyright (c) Yutong Zou, licensed under the MIT License.
+
+The tool-interception and sandbox re-rooting approach in index.js follows that
+project; the source-folder model, aliases, project editor, `@` menu group and
+skill discovery are original to this package.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# dsh-project-sources
 
-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.md) | **English**
+
+> Codex-style project sources for DeepSeek Harness: one workspace, many folders, each with an alias the agent can use.
+
+A DeepSeek Harness plugin bundle that attaches extra folders to a workspace. The session keeps the workspace as its `cwd`; every attached folder gets the **same read / write / edit / command permissions** under the session's current sandbox mode, and each one carries a short **alias** the model can refer to.
+
+- **Project editor** — “编辑项目” dialog from the session header, or the “📁 项目源文件夹” pill on the session-creation page. Add folders, rename aliases, remove them.
+- **Aliases in the conversation** — one system-prompt section maps every alias to its absolute path, so `@web/src/a.ts` is unambiguous to the model.
+- **`@` menu coverage** — the shipped `@` provider is single-root; this plugin contributes a companion group that searches every source (by alias, by folder name, or by absolute path).
+- **Source-folder skills** — `/` finds skills under `<source>/.dsh/skills`, `<source>/.agents/skills` and `<source>/skills`, recursively.
+- **No new tools** — `read`/`glob`/`grep` already work anywhere; `write`/`edit`/`pwsh`/`bash` are intercepted and re-rooted at the matching source.
+
+## Requirements
+
+- DeepSeek Harness **0.2.1-rc.5 … 0.2.x** (`engines.dsh: ^0.2.1-rc.5`)
+- Node.js ≥ 20
+
+## Install
+
+From the Web UI: **Settings → Plugins → Add**, then paste `dsh-project-sources`.
+
+From the CLI:
+
+```bash
+dsh plugin --profile <profile> add dsh-project-sources@0.1.0
+```
+
+Or from a local checkout (the agent tool `plugin_manager` accepts a directory):
+
+```text
+plugin_manager install_bundle   target: D:\work\dsh-project-sources
+```
+
+Restart the Host after a source change (the Host module is imported at boot); the browser bundle reloads on a page refresh.
+
+## Usage
+
+| Action | Where |
+| --- | --- |
+| Edit the project | “项目” button in the session header |
+| Edit before the first message | “📁 项目源文件夹” above the composer on the session-creation page |
+| Add a folder | Click “添加文件夹” → the OS folder chooser opens |
+| Rename | Type in the alias field of a row |
+| Remove | `×` on the row (the workspace itself cannot be removed) |
+
+Aliases must be letters/digits/`.`/`_`/`-`, at most 48 characters; duplicates get a `-2` suffix.
+
+## Where it stores data
+
+`<DSH_HOME>/storages/project-sources/<workspace-key>.json` — one record per workspace, outside every agent sandbox root. Only user-driven flows write it; the agent cannot add folders to itself.
+
+## Platforms
+
+| | Windows | macOS | Linux |
+| --- | --- | --- | --- |
+| Folder chooser | `powershell -STA` + `FolderBrowserDialog` | `osascript … choose folder` | falls back to the Host picker, then the manual path field |
+
+The sandbox re-rooting, `@` menu and skill discovery are platform-neutral. macOS support is implemented but not yet tested on a Mac.
+
+## Limitations
+
+- **One writable root per command.** A shell run writes inside only the directory its `workdir` resolves to. Pass an **absolute** `workdir` inside the source; a relative one resolves against the workspace, and `git -C <source>` / `cd <source>` inside the command does not widen the root.
+- The session `cwd` is fixed: there is no “primary folder” concept, and the workspace root stays the default working directory.
+- Cannot run beside another plugin that intercepts the same tool pipeline (e.g. `dsh-multi-folder`).
+- Background shell runs are supported through the jobs runtime, but a denial that happens after the call returns is only visible in `job_output`.
+
+## Development
+
+No build step. `npm test` runs both suites without the DSH runtime:
+
+```bash
+node test/smoke.mjs   # config store, interception, prompt, remote API
+node test/skills.mjs  # source-folder skill discovery
+```
+
+## Acknowledgements
+
+The tool-interception and sandbox re-rooting approach follows
+[dsh-multi-folder](https://github.com/AngelosZou/dsh-multi-folder) by Yutong Zou
+(MIT). See `NOTICE`.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,84 @@
+# dsh-project-sources
+
+**中文** | [English](README.md)
+
+> 给 DeepSeek Harness 的工作区附加多个文件夹：一个工作区、多个源目录，每个都有别名，模型可直接引用。
+
+这是一个 DeepSeek Harness 插件 bundle。会话的 `cwd` 仍然是主工作区；被附加的文件夹在**当前沙箱模式下拥有与主工作区相同**的读写、编辑与命令执行权限，并且每个文件夹都有一个简短的**别名**。
+
+- **项目编辑器**：会话头部的「项目」按钮，或新会话页输入框上方的「📁 项目源文件夹」。可添加文件夹、改别名、移除。
+- **会话里用别名引用**：系统提示词注入「别名 → 绝对路径」映射，`@web/src/a.ts` 对模型是明确的。
+- **`@` 菜单覆盖**：内置 `@` 是单根的，本插件贡献一个伴生分组，按别名、目录名或绝对路径搜索所有源目录。
+- **源目录里的 skill**：`/` 能找到 `<源目录>/.dsh/skills`、`<源目录>/.agents/skills`、`<源目录>/skills` 下的技能，递归多层。
+- **不新增任何工具**：`read`/`glob`/`grep` 本来就能跨目录；`write`/`edit`/`pwsh`/`bash` 命中源目录时被拦截，并把沙箱根重定到该目录。
+
+## 环境要求
+
+- DeepSeek Harness **0.2.1-rc.5 ～ 0.2.x**（`engines.dsh: ^0.2.1-rc.5`）
+- Node.js ≥ 20
+
+## 安装
+
+Web 界面：**设置 → 插件 → 添加**，填 `dsh-project-sources`。
+
+命令行：
+
+```bash
+dsh plugin --profile <profile> add dsh-project-sources@0.1.0
+```
+
+从本地目录（Agent 工具 `plugin_manager` 可以传目录）：
+
+```text
+plugin_manager install_bundle   target: D:\work\dsh-project-sources
+```
+
+改动源码后需要重启 Host（Host 模块在启动时 import）；浏览器端刷新页面即可。
+
+## 使用
+
+| 操作 | 位置 |
+| --- | --- |
+| 编辑项目 | 会话头部的「项目」按钮 |
+| 发第一条消息前编辑 | 新会话页、输入框上方的「📁 项目源文件夹」 |
+| 添加文件夹 | 点「添加文件夹」→ 弹出系统文件夹对话框 |
+| 改别名 | 直接编辑该行的别名输入框 |
+| 移除 | 该行的 `×`（工作区本身不能移除） |
+
+别名限字母/数字/`.`/`_`/`-`，最长 48 字符；重名自动加 `-2` 后缀。
+
+## 数据存放
+
+`<DSH_HOME>/storages/project-sources/<workspace-key>.json`，一个工作区一个文件，放在所有 Agent 沙箱根之外。只有用户操作会写入；Agent 无法给自己加目录。
+
+## 平台
+
+| | Windows | macOS | Linux |
+| --- | --- | --- | --- |
+| 文件夹选择器 | `powershell -STA` + `FolderBrowserDialog` | `osascript … choose folder` | 退回宿主 picker，再退回手动输入 |
+
+沙箱重定根、`@` 菜单、技能发现都与平台无关。macOS 分支已实现，但尚未在 Mac 上实测。
+
+## 已知限制
+
+- **一条命令只能写一个根**：shell 命令只能写入其 `workdir` 指向的目录。请传源目录的**绝对** `workdir`；相对路径会按工作区解析，命令里 `git -C <源>` / `cd <源>` 也不会扩大可写根。
+- 会话 `cwd` 固定：没有「主文件夹」概念，工作区仍是默认工作目录。
+- 不能与另一个拦截同一工具流水线的插件（如 `dsh-multi-folder`）同时启用。
+- 后台命令通过 jobs 运行时支持，但调用返回之后才发生的拒绝只能在 `job_output` 里看到。
+
+## 开发
+
+无构建步骤。`npm test` 不需要 DSH 运行时：
+
+```bash
+node test/smoke.mjs   # 配置存储、拦截、提示词、remote API
+node test/skills.mjs  # 源目录技能发现
+```
+
+## 致谢
+
+工具拦截与沙箱重定根的思路参考了 [dsh-multi-folder](https://github.com/AngelosZou/dsh-multi-folder)（作者 Yutong Zou，MIT），详见 `NOTICE`。
+
+## License
+
+MIT