@exagone313/dsh-podman 0.2.0-rc.2

package/docs/development.md

@@ -0,0 +1,142 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Development
+
+This page is for **contributors** building the plugin from this repository.
+
+## Repository layout
+
+- `src/` — the Cordis plugin (host half + browser client).
+- `cmd/dsh-podman-orchestrator/` and `cmd/dsh-podman-guest-agent/` — the two Go
+  binaries.
+- `internal/` — Go implementation of the orchestrator, guest agent, and protobuf
+  bindings.
+- `proto/` — the gRPC definitions.
+- `.github/workflows/` — CI and release automation.
+
+## Building
+
+Prerequisites: Go 1.27, Node ≥ 22, pnpm 12, and (for the browser half) the
+`@deepseek-ai/dsh-client-*` packages published on npm.
+
+```sh
+pnpm install
+pnpm run build       # tsc host + tsc client -> dist/, copies proto/ -> dist/grpc/proto/
+```
+
+The Go build tags skip the btrfs and devicemapper storage drivers, which need
+host C headers; `make` applies the same tags automatically.
+
+The `Makefile` wraps the common workflows:
+
+```sh
+make build-go       # build both Go binaries into bin/<os>-<arch>/
+make build          # build-go + pnpm-build
+make vet            # go vet with the build tags
+make test-go        # go test with the build tags
+make test           # test-go + pnpm test (JS tests, which run against dist/)
+make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
+make image          # build the orchestrator and guest-agent container images
+```
+
+`make image` depends on `LICENSE.pkg`: the `download-licenses` target runs the
+Go collector in `scripts/download-licenses`, which shells out to
+`go-licenses save` and gathers the project's MIT license plus every third-party
+Go license and Apache `NOTICE` into `LICENSE.pkg`. That file is gitignored
+(never committed) and is baked into the orchestrator and guest-agent images at
+`/usr/share/licenses/dsh-podman/LICENSE`; because workspace containers mount the
+guest-agent image, it also rides along into every workspace container.
+
+`pnpm test` runs `node --test dist/*.test.js`, so it requires `pnpm build` to
+have run first (the `test` target handles this).
+
+## Protobuf
+
+The `.proto` sources live in `proto/`; the generated Go bindings in
+`internal/genproto/` are committed. After changing a `.proto`, regenerate them
+with Buf (`buf generate`), which must be installed separately (it has no `make`
+target) — pin it with `go install github.com/bufbuild/buf/cmd/buf@v1.73.0`.
+Commit the `.proto` change together with the regenerated Go bindings.
+
+The JS side loads the raw `.proto` files at runtime via `@grpc/proto-loader`
+(copied to `dist/grpc/proto/` at build time); no TypeScript bindings are
+generated. Optionally validate the schema with `buf lint` and `buf breaking`.
+
+## Install development builds
+
+### Build
+
+```bash
+make  # builds plugin and go binaries
+make image  # build images
+```
+
+### Recreate containers
+
+```bash
+systemctl --user restart dsh dsh-podman-orchestrator
+```
+
+### Update plugin
+
+```bash
+npm pack
+v="$(jq -r .version package.json)"
+podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
+podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
+podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
+systemctl --user restart dsh
+```
+
+## Continuous integration
+
+CI (`.github/workflows/ci.yml`) runs on every branch push and pull request:
+
+- **actions-lint** — zizmor scans the workflows for insecure practices.
+- **go** — build, vet, tests, and govulncheck (Go vulnerabilities). Unfixed
+  findings don't fail the job; fixable ones do.
+- **js** — install, typecheck, build, tests, and `pnpm audit`.
+- **images** — builds the orchestrator and guest-agent images (runs only after
+  the test jobs pass).
+- **trivy** — filesystem vulnerability scan (unfixed ignored) and container
+  misconfiguration scan (DS-0002 excluded via `.trivyignore.yaml`).
+
+All third-party actions are pinned to full commit SHAs and checked by zizmor.
+
+## Releasing
+
+Releases are triggered by pushing a **bare semver tag** (`x.y.z`, no `v`;
+pre-releases like `1.0.0-rc.1` also work). The release workflow
+(`.github/workflows/release.yml`):
+
+1. Runs the tests, then builds both binaries for `linux/amd64` and
+   `linux/arm64`.
+2. Pushes the **orchestrator** and **guest-agent** images to GHCR
+   (`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`), tagged with the
+   version plus `latest` for stable releases (pre-releases never get `latest`).
+3. Publishes the plugin to **npm** (`@exagone313/dsh-podman`) with provenance;
+   pre-releases are published under the `next` dist-tag.
+4. Creates a **GitHub release** with auto-generated notes and attaches the
+   binaries and the npm tarball.
+
+The tag must match `package.json`'s version — the workflow fails otherwise — so
+bump both with the version script:
+
+```sh
+pnpm bump-version 0.1.1            # add --dry-run to validate only
+git push origin master 0.1.1
+```
+
+`scripts/bump-version.mjs` checks that the version is a semver release or
+pre-release that increases the current one, writes it to `package.json`, commits
+`chore: bump version to X`, and creates the tag; it pushes nothing, and it
+requires the `master` branch with a clean working tree. The tag is also what the
+built plugin and binaries report, since `scripts/generate-version.mjs` derives
+the embedded version from `git describe --tags`. Pre-releases (`1.0.0-rc.1`) are
+bumped the same way.
+
+The `NPM_TOKEN` secret must be configured on the repository for the npm step.

package/docs/development.zh.md

@@ -0,0 +1,135 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 开发
+
+本页面向从本仓库构建插件的**贡献者**。
+
+## 仓库结构
+
+- `src/` — Cordis 插件（宿主端 + 浏览器客户端）。
+- `cmd/dsh-podman-orchestrator/` 和 `cmd/dsh-podman-guest-agent/` — 两个 Go
+  二进制文件。
+- `internal/` — orchestrator、guest agent 和 protobuf 绑定的 Go 实现。
+- `proto/` — gRPC 定义。
+- `.github/workflows/` — CI 和发布自动化。
+
+## 构建
+
+前置要求：Go 1.27、Node ≥ 22、pnpm 12，以及（浏览器端所需的）发布在 npm 上的
+`@deepseek-ai/dsh-client-*` 包。
+
+```sh
+pnpm install
+pnpm run build       # tsc host + tsc client -> dist/, copies proto/ -> dist/grpc/proto/
+```
+
+Go 构建标签会跳过 btrfs 和 devicemapper 存储驱动，它们需要宿主机的 C
+头文件；`make` 会自动应用相同的标签。
+
+`Makefile` 封装了常见的工作流：
+
+```sh
+make build-go       # build both Go binaries into bin/<os>-<arch>/
+make build          # build-go + pnpm-build
+make vet            # go vet with the build tags
+make test-go        # go test with the build tags
+make test           # test-go + pnpm test (JS tests, which run against dist/)
+make download-licenses  # generate LICENSE.pkg from the project and third-party Go licenses
+make image          # build the orchestrator and guest-agent container images
+```
+
+`make image` 依赖 `LICENSE.pkg`：`download-licenses` 目标会运行
+`scripts/download-licenses` 中的 Go 收集器，它调用 `go-licenses save` 并将项目的
+MIT 许可证以及所有第三方 Go 许可证和 Apache `NOTICE` 汇总到 `LICENSE.pkg`
+中。该文件被 gitignore （从不提交），并被烘焙进 orchestrator 和 guest-agent
+镜像，位于 `/usr/share/licenses/dsh-podman/LICENSE`；由于工作区容器会挂载
+guest-agent 镜像，因此它也会随之进入每个工作区容器。
+
+`pnpm test` 运行 `node --test dist/*.test.js`，因此它要求先运行 `pnpm build`
+（`test` 目标会处理这一点）。
+
+## Protobuf
+
+`.proto` 源文件位于 `proto/`；生成的 Go 绑定位于
+`internal/genproto/`，会被提交。修改 `.proto` 后，需要使用单独安装的
+Buf（`buf generate`）重新生成（没有对应的 `make` 目标）——请用
+`go install github.com/bufbuild/buf/cmd/buf@v1.73.0` 固定版本。请将 `.proto`
+改动与重新生成的 Go 绑定一起提交。
+
+JS 端在运行时通过 `@grpc/proto-loader` 加载原始 `.proto` 文件（构建时复制到
+`dist/grpc/proto/`）；不生成 TypeScript 绑定。也可以使用 `buf lint` 和
+`buf breaking` 校验 schema。
+
+## 安装开发构建
+
+### 构建
+
+```bash
+make  # builds plugin and go binaries
+make image  # build images
+```
+
+### 重建容器
+
+```bash
+systemctl --user restart dsh dsh-podman-orchestrator
+```
+
+### 更新插件
+
+```bash
+npm pack
+v="$(jq -r .version package.json)"
+podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
+podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
+podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
+systemctl --user restart dsh
+```
+
+## 持续集成
+
+CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行：
+
+- **actions-lint** — zizmor 扫描工作流是否存在不安全实践。
+- **go** — 构建、vet、测试和 govulncheck（Go 漏洞）。未修复的
+  发现不会导致任务失败；可修复的会导致失败。
+- **js** — 安装、类型检查、构建、测试和 `pnpm audit`。
+- **images** — 构建 orchestrator 和 guest-agent 镜像（仅在测试任务通过后运行）。
+- **trivy** — 文件系统漏洞扫描（未修复的被忽略）和容器 错误配置扫描（DS-0002
+  通过 `.trivyignore.yaml` 排除）。
+
+所有第三方 actions 都锁定到完整的提交 SHA，并由 zizmor 检查。
+
+## 发布
+
+发布由推送**纯 Semver 标签**（`x.y.z`，不带 `v`； 像 `1.0.0-rc.1`
+这样的预发布同样有效）触发。发布工作流 （`.github/workflows/release.yml`）：
+
+1. 运行测试，然后为 `linux/amd64` 和 `linux/arm64` 构建两个二进制文件。
+2. 将 **orchestrator** 和 **guest-agent** 镜像推送到 GHCR
+   （`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`），并打上
+   版本号以及稳定版的 `latest` 标签（预发布永远不会获得 `latest`）。
+3. 将插件发布到 **npm**（`@exagone313/dsh-podman`），附带来源证明； 预发布在
+   `next` dist-tag 下发布。
+4. 创建带有自动生成说明的 **GitHub release**，并附上 二进制文件和 npm tarball。
+
+标签必须与 `package.json`
+中的版本一致——否则工作流会失败——因此请用版本脚本同时更新两者：
+
+```sh
+pnpm bump-version 0.1.1            # 加上 --dry-run 则仅校验
+git push origin master 0.1.1
+```
+
+`scripts/bump-version.mjs` 会检查版本是否为递增的 Semver
+正式版或预发布版，将其写入 `package.json`，提交
+`chore: bump version to X`，并创建标签；它不会推送，且要求处于 `master`
+分支且工作区干净。标签同时也是构建出的插件与二进制文件所报告的版本，因为
+`scripts/generate-version.mjs` 从 `git describe --tags`
+推导嵌入的版本。预发布版（`1.0.0-rc.1`）也用同样的方式递增。
+
+npm 步骤要求仓库配置 `NPM_TOKEN` 密钥。

package/docs/install-dsh-and-dsh-podman.md

@@ -0,0 +1,165 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# Install DeepSeek Harness & dsh-podman with rootless Podman
+
+## Goals
+
+The goal of this guide is to install:
+
+- [DeepSeek Harness](https://deepseek.com/harness), referred to later as _dsh_
+- the dsh-podman plugin in dsh, which replaces host filesystem and shell access
+- the dsh-podman orchestrator, a separate Podman container that integrates with
+  Podman
+
+Having the dsh plugin and the orchestrator running as separate containers is an
+important part of the security design of dsh-podman: dsh itself doesn't have
+direct access to Podman, only the orchestrator does, with limitations. dsh
+shouldn't be able to escalate privileges using this path, as the capabilities
+provided to dsh are constrained:
+
+- the names of pods, containers, volumes and secrets are prefixed with
+  `dsh-podman-`
+- mounted paths are limited to bind-mounted project directories and managed
+  volumes
+- containers are dealt with separately for each dsh workspace.
+
+Nevertheless, it is recommended to run dsh as a dedicated user instead of your
+main user.
+
+Note that, for now, network access is not constrained, but support for this
+could be added in the future.
+
+## Terminology
+
+- **dsh**: DeepSeek Harness, a plugin-oriented AI agent harness developed by
+  DeepSeek
+- **dsh-podman**: this project
+- **dsh-podman plugin**: the plugin installed in dsh, which provides tools to
+  agents and a UI for manual settings, and connects to the orchestrator;
+  referred to later as _plugin_
+- **dsh-podman orchestrator**: the daemon that receives connections from the
+  dsh-podman plugin, has access to the Podman socket and manages containers and
+  other resources; it runs in a container; referred to later as _orchestrator_
+- **Podman socket**: while the Podman client can be used without a daemon, it is
+  still possible to enable management through a socket, which is required by the
+  orchestrator to work as if it were running on the host system
+- **guest container**: a container created by the dsh-podman orchestrator, in
+  relation to a dsh workspace
+- **dsh workspace**: in dsh, a project uses the name _workspace_, with its own
+  dedicated directory
+
+## Requirements
+
+- A user to run dsh as (not root)
+- A Linux distribution powered by systemd
+- Podman 5 or later; Podman 6 is recommended
+- A systemd session as your dsh user (**`sudo -iu` will not work**):
+  - by using machinectl (recommended; on some distributions, this command is
+    part of the `systemd-container` package; it needs to be run as root or as
+    part of the _wheel_ group):
+    ```bash
+    machinectl shell --uid=your-username
+    ```
+  - by connecting via SSH
+  - by connecting on a tty
+
+## Recommendations
+
+- If you want to start dsh at boot,
+  [enable _user lingering_ for your user](https://www.freedesktop.org/software/systemd/man/loginctl.html#enable-linger%20USER%E2%80%A6)
+  as root:
+  ```bash
+  loginctl enable-linger your-username
+  ```
+- Ensure that Podman is working correctly as your dsh user (⚠️ the first command
+  may stop existing containers!):
+  ```bash
+  podman system migrate
+  podman run --rm quay.io/podman/hello
+  podman rmi quay.io/podman/hello
+  ```
+
+## Preparation
+
+- You need to choose a project directory. This directory will be mounted
+  read-only in dsh (necessary for the integrated project manager) and read-write
+  in guest containers. In this guide we will use `${HOME}/project`
+  (`%h/project`) but you are free to choose another path, as long as your user
+  has read-write access to it.
+- Create a project inside the chosen directory. This will be useful to create a
+  workspace in dsh to validate the setup.
+
+## Installation
+
+### dsh setup
+
+This installation uses
+[Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html),
+which adds Podman integration into systemd.
+
+1. Create the Quadlet directory for your user:
+   ```bash
+   mkdir -p ~/.config/containers/systemd
+   ```
+2. Copy the files [dsh.container](../quadlet/dsh.container) and
+   [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
+   to `~/.config/containers/systemd/`.
+   - Adapt the files to your desired project directory if you wish to change it.
+3. Reload systemd session configuration:
+   ```bash
+   systemctl --user daemon-reload
+   ```
+4. Check if there are errors in the configuration:
+   ```bash
+   journalctl --user -e
+   ```
+5. Start dsh and dsh-podman-orchestrator:
+   ```bash
+   systemctl --user start dsh dsh-podman-orchestrator
+   ```
+6. Check if there are startup errors from either container:
+   ```bash
+   journalctl --user -eu dsh
+   ```
+   ```bash
+   journalctl --user -eu dsh-podman-orchestrator
+   ```
+7. View the dsh container logs:
+   ```bash
+   podman logs dsh
+   ```
+8. Visit the given URL in the form `http://127.0.0.1:3080/?token=xxx` to access
+   dsh.
+9. Once your web browser has saved this token, you'll be able to access dsh with
+   the URL [http://127.0.0.1:3080/](http://127.0.0.1:3080/).
+
+### dsh-podman plugin installation
+
+1. Run this command to install the dsh-podman plugin:
+   ```bash
+   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
+   ```
+2. Restart dsh to complete the installation:
+   ```bash
+   systemctl --user restart dsh
+   ```
+
+## Verification
+
+- Open **Settings → Plugins → dsh-podman**: the card should list the base images
+  and, for a workspace, offer to create its default container.
+- In a dsh session, run a shell command. It should execute inside a Podman
+  container for the current workspace (the plugin auto-creates the workspace's
+  default container on first use).
+
+## Enable daily auto-updates (optional)
+
+This requires enabling lingering for your user.
+
+```bash
+systemctl --user enable --now podman-auto-update.timer
+```

package/docs/install-dsh-and-dsh-podman.zh.md

@@ -0,0 +1,145 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# 使用 rootless Podman 安装 DeepSeek Harness 与 dsh-podman
+
+## 目标
+
+本指南的目标是安装：
+
+- [DeepSeek Harness](https://deepseek.com/harness)，下文简称 _dsh_
+- dsh 中的 dsh-podman 插件，它取代了宿主的文件系统和 shell 访问
+- dsh-podman 编排器，一个与 Podman 集成的独立 Podman 容器
+
+将 dsh 插件和编排器作为独立的容器运行，是 dsh-podman 安全设计的重要一环： dsh
+本身不能直接访问 Podman，只有编排器可以，并且受到限制。dsh
+不应能通过这条路径提权，因为提供给 dsh 的权限能力是受限的：
+
+- pod、容器、卷和 secret 的名称都以 `dsh-podman-` 为前缀
+- 挂载路径仅限于绑定挂载的项目目录和受管理的卷
+- 每个 dsh 工作区分别管理各自的容器。
+
+尽管如此，仍建议使用专用用户运行 dsh，而不是你的主用户。
+
+请注意，目前网络访问不受限制，但未来可能会添加对此的支持。
+
+## 术语
+
+- **dsh**：DeepSeek Harness，由 DeepSeek 开发的面向插件的 AI agent harness
+- **dsh-podman**：本项目
+- **dsh-podman 插件**：安装在 dsh 中的插件，它为 agent 提供工具、提供手动设置
+  UI，并连接编排器；下文简称 _plugin_
+- **dsh-podman 编排器**：接收来自 dsh-podman 插件连接的守护进程，可访问 Podman
+  套接字并管理容器和其他资源；它在容器中运行；下文简称 _orchestrator_
+- **Podman 套接字**：虽然 Podman
+  客户端可以在没有守护进程的情况下使用，但仍然可以通过套接字启用管理，这是编排器以仿佛在主机系统上运行的方式工作所必需的
+- **guest 容器**：由 dsh-podman 编排器创建的容器，与 dsh 工作区相关联
+- **dsh 工作区**：在 dsh 中，项目使用 _workspace_ 这一名称，并有自己的专用目录
+
+## 要求
+
+- 一个用于运行 dsh 的用户（不能是 root）
+- 基于 systemd 的 Linux 发行版
+- Podman 5 或更高版本；推荐使用 Podman 6
+- 以你的 dsh 用户身份存在的 systemd 会话（**`sudo -iu` 无法工作**）：
+  - 通过 machinectl（推荐；在某些发行版上，此命令属于 `systemd-container`
+    包；需要以 root 身份或作为 _wheel_ 组的成员运行）：
+    ```bash
+    machinectl shell --uid=your-username
+    ```
+  - 通过 SSH 连接
+  - 通过 tty 连接
+
+## 建议
+
+- 如果你想在开机时启动 dsh，请以 root 身份
+  [为你的用户启用 _user lingering_（常驻）](https://www.freedesktop.org/software/systemd/man/loginctl.html#enable-linger%20USER%E2%80%A6)：
+  ```bash
+  loginctl enable-linger your-username
+  ```
+- 确保 Podman 在你的 dsh 用户下能正常工作（⚠️ 第一条命令可能会停止现有容器！）：
+  ```bash
+  podman system migrate
+  podman run --rm quay.io/podman/hello
+  podman rmi quay.io/podman/hello
+  ```
+
+## 准备工作
+
+- 你需要选择一个项目目录。该目录在 dsh
+  中以只读方式挂载（对于内置的项目管理器是必需的），在 guest
+  容器中以读写方式挂载。在本指南中，我们将使用
+  `${HOME}/project`（`%h/project`），但你可以自由选择其他路径，只要你的用户对该路径具有读写访问权限即可。
+- 在所选目录中创建一个项目。这将有助于在 dsh 中创建工作区以验证安装是否成功。
+
+## 安装
+
+### dsh 配置
+
+本次安装使用
+[Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)，
+它为 systemd 增加了 Podman 集成。
+
+1. 为你的用户创建 Quadlet 目录：
+   ```bash
+   mkdir -p ~/.config/containers/systemd
+   ```
+2. 将文件 [dsh.container](../quadlet/dsh.container) 和
+   [dsh-podman-orchestrator.container](../quadlet/dsh-podman-orchestrator.container)
+   复制到 `~/.config/containers/systemd/`。
+   - 如果你希望更改项目目录，可相应调整这些文件。
+3. 重新加载 systemd 会话配置：
+   ```bash
+   systemctl --user daemon-reload
+   ```
+4. 检查配置中是否有错误：
+   ```bash
+   journalctl --user -e
+   ```
+5. 启动 dsh 和 dsh-podman-orchestrator：
+   ```bash
+   systemctl --user start dsh dsh-podman-orchestrator
+   ```
+6. 检查任一容器是否有启动错误：
+   ```bash
+   journalctl --user -eu dsh
+   ```
+   ```bash
+   journalctl --user -eu dsh-podman-orchestrator
+   ```
+7. 查看 dsh 容器日志：
+   ```bash
+   podman logs dsh
+   ```
+8. 访问形如 `http://127.0.0.1:3080/?token=xxx` 的给定 URL 以使用 dsh。
+9. 浏览器保存该令牌后，即可通过 [http://127.0.0.1:3080/](http://127.0.0.1:3080/)
+   访问 dsh。
+
+### dsh-podman 插件安装
+
+1. 运行以下命令安装 dsh-podman 插件：
+   ```bash
+   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
+   ```
+2. 重启 dsh 以完成安装：
+   ```bash
+   systemctl --user restart dsh
+   ```
+
+## 验证
+
+- 打开 **Settings → Plugins →
+  dsh-podman**：卡片应列出基础镜像，并针对工作区提供创建其默认容器的选项。
+- 在 dsh 会话中运行一条 shell 命令。它应在当前工作区的 Podman
+  容器内执行（插件会在首次使用时自动创建工作区的默认容器）。
+
+## 启用每日自动更新（可选）
+
+这需要为你的用户启用 lingering。
+
+```bash
+systemctl --user enable --now podman-auto-update.timer
+```