# dsh-git-workbench

Git and GitHub pull-request workflows for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), exposed both as model tools and as an integrated Web sidebar workbench.

> Status: experimental. DeepSeek Harness is currently a developer preview and its plugin interfaces may change. This release targets the exact `0.1.0-rc.6` DSH package line.

[简体中文](./README.zh-CN.md)

## What it provides

- Repository status, staged/unstaged diffs, history, and local branches
- Stage, unstage, safe restore, commit, branch create/switch/safe-delete
- Fetch, fast-forward pull by default, and push without force options
- GitHub pull requests: list, view, create, edit, checkout, merge, and comment
- A DSH Web sidebar panel for changes, text-file editing, commits, branches, history, and pull requests
- Model-facing tools for the same workflows: `git_status`, `git_diff`, `git_log`, `git_stage`, `git_commit`, `git_branch`, `git_sync`, and `github_pr`

This project aims for Git/GitHub workflow parity with coding agents such as Codex. It does not claim to reproduce unrelated proprietary Codex features.

<img width="1844" height="1377" alt="屏幕截图 2026-08-15 163354" src="https://github.com/user-attachments/assets/d6642e89-388c-4b91-a686-7ca109bc8dba" />

## Requirements

- Node.js `^22.19.0` or `>=24`
- DeepSeek Harness `0.1.0-rc.6`
- Git on `PATH`
- [GitHub CLI](https://cli.github.com/) on `PATH` and authenticated with `gh auth login` for pull-request features

The plugin never stores GitHub tokens. Authentication remains owned by Git and `gh`.

## Install from GitHub

Until an npm release exists, install from a GitHub repository:

```bash
dsh plugin --profile web add github:FlutterSoul/dsh-git-workbench
```

Git-source installation runs this package's `prepare` build. pnpm 10 and later intentionally reject that on the first attempt. Review the repository, then copy the exact package key printed by DSH into `$DSH_HOME/profiles/web/pnpm-workspace.yaml` and retry. With pnpm 11.19 or later, the repository-scoped form is:

```yaml
allowBuilds:
  'dsh-git-workbench@git+https://github.com/FlutterSoul/dsh-git-workbench.git': true
```

This grants build permission only to this Git repository; do not disable pnpm's build safeguards globally. For reproducible installations, append a trusted commit or tag to the GitHub specifier.

Start DSH Web:

```bash
dsh --profile web
```

The **Git** entry appears in the sidebar footer. It follows the current task's registered workspace.

## Configuration

The bundle inserts the plugin with defaults through `cordis.patch.yml`. Configure its Loader entry in the DSH profile when non-default values are needed:

| Option | Default | Purpose |
| --- | --- | --- |
| `gitBinary` | `git` | Git executable |
| `ghBinary` | `gh` | GitHub CLI executable |
| `commandTimeoutMs` | `120000` | Per-process timeout |
| `maxOutputBytes` | `4194304` | Maximum captured command output |
| `maxFileBytes` | `1048576` | Maximum file size accepted by the editor |
| `maxRequestBytes` | `2097152` | Maximum Web API request body |
| `defaultRemote` | `origin` | Default fetch/pull/push remote |
| `defaultPullMode` | `ff-only` | `ff-only`, `rebase`, or `merge` |
| `pushBeforePrCreate` | `true` | Push the head before creating a PR |
| `mutationApproval` | `all` | Model-tool approval policy: `all`, `destructive`, or `none` |
| `allowedRoots` | `[]` | Additional absolute roots the browser UI may operate in |

The UI accepts registered DSH workspaces by default. `allowedRoots` is for deployments that intentionally expose additional workspace trees.

## Safety model

- Commands use `spawn` with `shell: false`; arguments are never concatenated into a shell command.
- Git and GitHub CLI interactive prompts and pagers are disabled.
- Mutations are serialized per repository.
- Model-initiated mutations request approval by default. A missing approval service fails closed.
- Browser calls require same-origin requests and are constrained to registered/configured workspaces.
- Text-file saves use an expected SHA-256 hash, preventing silent overwrite after concurrent edits.
- Force push, forced branch deletion, `git clean`, arbitrary Git arguments, and arbitrary `gh` arguments are not exposed.
- “Discard” only calls `git restore --worktree` for explicit tracked paths; it never deletes untracked files.

UI button clicks are direct user actions. The UI asks for confirmation before discard, branch deletion, and merge.

## Development

```bash
pnpm install --ignore-scripts
pnpm check
pnpm pack --dry-run
```

For a local DSH profile:

```bash
dsh plugin --profile web add ./path/to/dsh-git-workbench
npx @deepseek-ai/dsh web
```

The test suite creates disposable Git repositories and does not contact GitHub. Live PR verification requires a repository and authenticated `gh` account under your control.

## Architecture

```text
DSH agent tools ─┐
                 ├─ GitWorkbench ── git / gh child processes
DSH Web panel ─ API ┘
       │
       └─ sidebar.footer.action client slot
```

`src/git.ts` owns all Git/GitHub operations and path validation. `src/tools.ts` is the model-facing adapter. `src/api.ts` is the constrained same-origin Web adapter. `src/client/` contains the sidebar UI.

## Scope and limitations

- Text editing is UTF-8 only. Binary files and files over `maxFileBytes` remain diff-only.
- GitHub operations currently use GitHub CLI and GitHub-hosted pull requests; other forges are not implemented.
- Conflict resolution is shown through status and file editing, but no semantic merge editor is included.
- The plugin does not create repositories, rewrite history, manage credentials, or bypass branch protection.

## License

[MIT](./LICENSE)