dsh-knj-version-control

Readme

# dsh-knj-version-control

KNJ 家族插件：在 DSH Web 右侧栏提供 **Version Control** 工作台（Git Local Changes / Commit / Update / Push / 切换分支，全部走预览确认的安全流程）。通过公共 `dsh-better-sidebar.registerTab()` API 集成，不导入也不修改 Better Sidebar 私有 UI/状态/Git 代码。

## 宿主兼容性

- **Better Sidebar**：`peerDependencies: { "dsh-better-sidebar": ">=0.15.2" }`，并标记为 **optional**。
  实测 `registerTab(descriptor: TabDescriptor): () => void` 的签名与 `TabDescriptor` 字段在 **0.15.2 / 0.16.1 / 0.17.1 / 0.18.0** 间完全一致（0.19.1 仅新增可选字段 `description`），本插件只使用 `id / title / icon / order / single / badge / component`。
  peer 标 optional 意味着：宿主缺少 Better Sidebar 或版本更低时，**安装不会被阻断**，插件运行时会自检并在控制台告警后优雅退出（不影响其他插件）。
- **不锁死宿主版本**：本插件不对 `dsh-better-sidebar` 施加精确版本钉（不使用 `overrides`）。若你的 profile 需要统一某个 sidebar 版本，请在 profile 的 `pnpm-workspace.yaml` 里用 `overrides` 自行决定。


## Install for the Web profile

From the DSH install checkout, add this local package through the DSH plugin/profile path (do not copy files directly into `node_modules`):

```powershell
dsh plugin --profile web add D:\workspace\iobs_pro\plugins\dsh-knj-version-control
```

Restart or rebuild/reload the affected DSH Web artifacts as required by your installed DSH version, then refresh the existing GUI at `http://127.0.0.1:3080`.

`package.json` is UTF-8 **without BOM**. DSH reads profile and plugin metadata with bare `JSON.parse`; adding a BOM can prevent startup.

## Prerequisites

- Git must be installed and available as `git` on the DSH host PATH.
- The active DSH session needs a workspace. A non-Git workspace remains readable and shows a non-repository state.
- Git commit identity must be preconfigured by the user; this plugin never changes identity, remote, credential, or other Git configuration.

## Workbench layout (v1)

The **Version Control** tab registers with an icon, a change-count **badge** on the sidebar tab, and a `single` instance policy (reopening focuses the existing tab). Inside the tab:

- **Toolbar** — branch pill (current branch + `↑ahead ↓behind`), refresh, and Update (fetch + fast-forward pull with preview).
- **Status line** — HEAD branch, upstream, and clean/`N change(s)` state.
- **View tabs** — **Changes** (default), plus **Log** and **Console** entries that are reserved for phase two (they render a reserved state and load no data in v1).
- **Local Changes** — changed files grouped by type (Modified / Added / Deleted / Untracked / Conflicted) with per-group counts, collapse toggles, status chips, and selection checkboxes.
- **Staging (single file, several files, or a whole group)** — when the repository advertises Git staging, each non-conflicted row carries its own 「暂存」 / 「取消暂存」 action, the selection area offers 「暂存所选 (N)」 / 「取消暂存所选 (N)」 for arbitrary multi-file staging, and each group head offers 「全部暂存」 plus 「全部取消暂存」 while it holds staged paths. Rows carrying index changes are marked **已暂存** (a partially staged row shows both actions). Conflicted rows deliberately expose no staging action: `git add` on a conflicted path declares a resolution, and conflicts stay resolved outside the workbench.
- **Dedicated diff page** — activating a file row opens a dedicated diff view (working-tree diff preferred, staged fallback) with a back control. Side-by-side is reserved.
- **Branch picker** — clicking the branch pill lists local and remote branches with search. Local branches switch through a preview-and-confirm flow; remote branches show a reserved hint (they require a local tracking branch in a later phase).
- **Commit box** — message area, primary **Commit**, and **Commit and Push…** which chains a commit confirmation followed by a fresh Push confirmation. Amend is reserved. The box states the commit scope (`git commit --only` over the checked files) so index state is never mistaken for commit content.
- Confirmation modals report exactly what will run (target branch/remote, incoming/outgoing commits, dirty-worktree warnings, pre-commit staging) before any write.
- **Failure detail dialog** — a failed commit, push, update, branch switch, or staging action opens a dismissible dialog with the mapped summary, the host failure code, and Git's own output (expandable, selectable, copyable), instead of a transient toast. A failure raised inside a confirmed operation replaces the confirmation dialog rather than closing with it.

## Safety behavior

- No arbitrary command input: all Git calls use `execFile('git', fixedArgs)`.
- Local Changes, Diff, Log, and branch listing are structured Git operations.
- Stage/unstage affect only selected, validated relative paths; they change the Git index only (never worktree content) and are reversible through the opposite action.
- Commit, Push, and branch **switch** first produce a preview token, then require explicit confirmation. Branch switching runs a plain `git switch`; a dirty worktree is reported before confirmation and Git decides carry-on-conflict vs. rejection.
- Tokens are root-, operation-, argument-, fingerprint-, and expiry-bound; changed repository state invalidates them and valid tokens are consumed once.
- **Update (merge-capable):** fetch always runs first. A fast-forward update — clean or dirty — runs `git pull --ff-only` directly on request with no confirmation dialog (still guarded by a fingerprint-bound preview token; Git refuses to overwrite uncommitted changes and any refusal is shown). When history has diverged, the update is labeled as a merge (`git pull --no-rebase`), requires explicit confirmation, warns that conflicts may result, and reports any conflicted paths for you to resolve externally — it never auto-resolves, auto-stashes, rebases, force-pushes, or retries.
- The plugin never auto-stashes, merges, rebases, force-pushes, configures credentials, or retries a rejected push.

### Busy feedback

Toolbar actions show in-flight state: while a snapshot refresh, preview, confirm, stage, or update is running, the status line shows a spinner with a short message and the toolbar buttons disable (the active one spins). Row and selection staging actions disable for the same window, so only one Git write is ever in flight.

### Known v1 behavior notes (by design)

- **Staging goes through the same-origin `/stage` endpoint directly** rather than through a preview token: Git staging has no preview surface in this version (the preview kinds are commit/update/push/switch), the endpoint is same-origin- and workspace-root-guarded, and the operation only changes the reversible Git index. The confirmed operations remain fingerprint-protected. A rejected staging write is reported with its `code` and Git's own output.
- **Staging is linked to commit selection:** staging a path also checks it for commit, and unstaging clears the check, so a staged file is never silently missing from the commit. The commit itself is still scoped to the checked paths — verified against Git: with `a.txt` and `b.txt` both staged and further modified, `git commit --only -- a.txt` committed `a.txt`'s worktree content, left `b.txt`'s staged content staged and uncommitted, and index state never changed what the commit contained.
- **「提交前暂存已选」 is a real option, off by default.** When enabled, the flow is `/stage` (checked paths) → `/preview` → confirmation → `/confirm`. The staging write must precede the preview because staging changes the repository fingerprint, which would invalidate an already-issued preview token; the confirmation dialog reports whether the write will run.
- **Diff captions** say "工作区 vs HEAD". For a partially staged file the shown diff is the unstaged delta; staged hunks are included in a later phase.
- **No operation history.** The failure detail dialog is the only, and mandatory, surface for a Git diagnostic; dismissing it discards the text (the reserved Console view remains a phase-two placeholder). Repository-load failures keep the persistent note card instead of a modal.

## SVN boundary

This first release is Git-only. The host workflow separates common status/diff/commit/update/history concepts from the Git-only staging capability, so a real SVN adapter can be added later without making staging a common requirement.