yangdongzhen590/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):

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.