# dsh-git-chain

**English · [中文](README.md)**

A Git commit graph plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/DeepSeek-Harness). It renders repository history as a readable SVG lane graph and brings commit details, full diffs, scoped history, filtering, and guarded local branch switching into the same sidebar workflow.

> Current version: `0.1.1` · Stable · [GitHub Release](https://github.com/ShinonomeAya/dsh-git-chain/releases/tag/v0.1.1) · MIT License

## Why dsh-git-chain

- **See topology clearly**: continuous lanes, nodes, merge joins, and branch edges represent the Git DAG instead of text glyphs.
- **Stay in one workflow**: mounts as a `dsh-better-sidebar` tab when available, with an input-chip and floating-panel fallback.
- **Move from history to evidence**: inspect authors, parents, changed files, and a lazy-loaded unified diff from any commit.
- **Switch branches safely**: checks conflicts, in-progress Git operations, other worktrees, and files that could be overwritten before switching.
- **Choose the right scope**: browse all refs, the current branch, an exact local branch, or the current `HEAD`'s first-parent history; the UI supports Chinese and English.

This is `0.1.1` Stable. Installation, upgrade, uninstall, reinstall, and fallback acceptance passed on Windows 11 with DSH Desktop `2.0.2.0`; see the compatibility matrix before using another DSH/OS combination.

## Screenshots

The full graph shows branch lanes, merge nodes, the current branch, and refs. First-parent mode focuses on the mainline of the current `HEAD`.

<p align="center">
  <img src="smoke/01-tab-graph.png" alt="Full Git commit graph" width="420">
  <img src="smoke/08-tab-first-parent.png" alt="First-parent Git commit graph" width="420">
</p>

## Features

### Git history and filtering

- Reads Git history with parent relationships and decorations in topological order.
- Provides server-side scopes for all refs, the current branch, and an exact local branch.
- Provides first-parent mode for the current `HEAD` while retaining merge metadata.
- Filters the loaded history window instantly by subject, author, ref, or commit OID.
- Uses fixed row heights, virtual scrolling, and stable lane identities for long commit lists.

### Commit details and diffs

- Shows author, committer, timestamps, parents, and changed files.
- Uses file-status badges and insertion/deletion counts to make changes easy to scan.
- Loads unified diffs on demand; the Host caps each response at 1 MB to keep large changes from taking over the UI.

### Branch switching and refresh

- Lists local branches and keeps the current-branch checkmark in sync.
- Uses `git switch --no-guess` and never implicitly creates or guesses a remote branch.
- The Host publishes external Git changes over SSE and throttles refreshes when the window regains focus.

## Installation

### Install from source into DSH

Requirements:

- DSH `>= 0.1.1-rc.1`
- Node.js `>= 22.19.0`
- Git available on the system `PATH`

```sh
git clone https://github.com/ShinonomeAya/dsh-git-chain.git
cd dsh-git-chain
pnpm install
pnpm run build
dsh plugin --profile desktop add link:/absolute/path/to/dsh-git-chain
```

Restart DSH so the Host-side plugin and bundle patch take effect, then open **Git Chain** from the sidebar.

Remove it with:

```sh
dsh plugin --profile desktop remove dsh-git-chain
```

## Development and verification

```sh
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
node scripts/browser-smoke.mjs
```

The current release gate covers both TypeScript projects, 55 unit/integration tests, Host/Client builds, and real Chromium checks for the full graph, first-parent mode, details, diffs, filtering, branch menus, fallback UI, and responsive layouts. Smoke screenshots are written to `smoke/`.

Open-source docs: [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md) · [Compatibility](docs/COMPATIBILITY.md) · [Community submission plan](docs/COMMUNITY-SUBMISSION.md) · [Release lifecycle plan](docs/RELEASE-LIFECYCLE-PLAN.md)

## Architecture

```text
DSH Web GUI                         DSH Host
┌──────────────────────────┐       ┌─────────────────────────────┐
│ better-sidebar tab       │ HTTP  │ workspace-gated Git service │
│ or fallback panel        │ ────► │ /git-chain/* JSON + SSE     │
│ React + SVG graph        │       │ Node + ctx.subprocess + Git  │
└──────────────────────────┘       └─────────────────────────────┘
```

- **Host**: invokes Git through `ctx.subprocess` and exposes workspace, status, branches, graph, show, diff, and guarded switch operations.
- **Client**: React renders the SVG lanes, node interactions, virtual list, filtering, and detail view.
- **Layout**: a pure layout snapshot carries lane identity, node types, merge edges, window boundaries, and node-entry semantics so lines stay connected and colors remain stable when columns move.
- **Build**: `tsdown` produces separate Host and browser Client bundles in the dual-face Cordis format expected by DSH.

## Security boundaries

- Git routes accept only registered DSH workspaces and validate their canonical paths.
- Requests are loopback-only by default; paired-device access still requires an additional trust credential.
- Mutation routes require `application/json`.
- Branch names and commit OIDs are allowlisted before reaching Git; commands use argv instead of shell-string concatenation.
- Branch switches are rejected when conflicts, in-progress operations, another worktree, or overwrite risks are detected.

## Known limitations

- Text filtering currently applies only to the loaded window; full-history server-side search by subject, author, or file is planned.
- The layout uses a minimal-lane strategy, so rare complex diamond merges can have slight curve overlap.
- Virtualized windows clip lane edges at their boundaries; overscan reduces visible jumps.
- A full diff response is capped at 1 MB.

## Roadmap and feedback

Planned work includes parent-chain hover highlighting, keyboard navigation, commit comparison, full-history server queries, pagination, and incremental updates. See [docs/ROADMAP.md](docs/ROADMAP.md) for the research, architecture decisions, and phased plan.

Please use [GitHub Issues](https://github.com/ShinonomeAya/dsh-git-chain/issues) for bugs and improvement ideas. Do not publish sensitive information in a public issue.

## License

[MIT](LICENSE)