dsh-git-scm 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-plugins contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,256 @@
1
- # Temporary Holding Version
1
+ # dsh-git-scm
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Git source-control panel for the DeepSeek Harness Web UI, modelled on VS Code's
4
+ Source Control view and GitLens' repository tree. It opens as a page in the right
5
+ sidebar and works on the checkout of the Session's current working directory.
6
+
7
+ ## What it shows
8
+
9
+ - **Repository header**: repository name, a status-bar-style branch chip whose
10
+ branch name opens a searchable branch switcher (local and remote branches,
11
+ with the dirty `*` / staged `+` markers and ahead/behind counts) and whose
12
+ cloud control publishes the branch when it has no upstream, hover tooltips
13
+ naming the repository, branch, and action, upstream, and the last fetch time.
14
+ - **Publish a branch**: while the current branch has never been pushed the
15
+ commit action becomes **Publish Branch** and the header's push control routes
16
+ a missing remote into the publish dialog instead of failing: choose a private
17
+ or public GitHub repository (created through an authenticated `gh` CLI,
18
+ default name from the folder) or fall back to any custom remote URL. After
19
+ the push the branch tracks its new upstream and the panel returns to the
20
+ ordinary commit and push controls.
21
+ - **Not a Git repository yet**: a Session directory outside Git shows an empty
22
+ state with two actions and a refresh control. **Initialize repository** runs
23
+ `git init -b main` and reads the new checkout; **Publish to Git** initializes
24
+ it, stages the working tree, creates the first commit (generating its message
25
+ when a model route is configured, else `Initial commit`), and continues into
26
+ the GitHub publish dialog; **Refresh** re-reads the directory after it was
27
+ changed outside the panel.
28
+ - **Commit messages from the model**: the message field carries a sparkle
29
+ control that asks the app's configured default model to write the message
30
+ from the current changes (staged changes win; the working tree is described
31
+ when nothing is staged) or, when the field already holds a draft, to improve
32
+ it in place. The prompt carries the changed paths, the recent commit subjects
33
+ as a style reference, and the panel language, and the commit menu offers the
34
+ same action. Holding the sparkle control (or right-clicking it) opens its
35
+ generation rules: language (follow the app, Chinese, or English) and style.
36
+ `automatic` mirrors the repository's recent habit — whether subjects carry a
37
+ Conventional Commits type prefix and whether commits have bodies;
38
+ `Conventional Commits` always requires a type prefix; `single-line subject`
39
+ emits no body; `subject with a detailed body` always appends 2-4 bullet
40
+ points. The rules persist for the profile. A language chosen in the
41
+ rules also applies when the control improves an existing draft, while the
42
+ default keeps that draft's language. The model seam comes from the Host's own
43
+ runtime, so this package keeps no LLM dependency.
44
+ - **Changes**: staged changes and working-tree changes (modified, added,
45
+ deleted, renamed, copied, conflicting, untracked).
46
+ - **Change lists right under the repository header**: the staged and
47
+ working-tree sections follow the header directly; the header row itself
48
+ carries the refresh, fetch, pull, push, and bulk-action controls, so no
49
+ separate "Changes" group row takes space.
50
+ - **A collapsible Git repositories group** (branches, remotes, stashes, tags)
51
+ whose sections are indented under it; every section collapses on its own and
52
+ the group title carries no counter.
53
+ - **Docked comparison**: clicking a changed file, a commit's file, or a stash
54
+ opens its comparison in a pane that docks below the list by default (a
55
+ draggable divider resizes it and the size is remembered) and can be switched
56
+ to dock on the right, where both the divider and the pane's own left edge
57
+ resize its width (double-clicking a divider restores the default size); the
58
+ divider is a layout-free seam that sits exactly on the pane border and
59
+ highlights on hover, and the dock
60
+ always leaves the list at least 300px wide (a narrower panel shrinks the
61
+ preview instead). Rows carry
62
+ old and new line numbers, long unchanged runs collapse to their edges and
63
+ expand on click, the pane switches between single-column and side-by-side
64
+ views, expands to nearly the whole panel, and searches its content with
65
+ match highlighting, a match counter, and next/previous stepping. `⌘F` /
66
+ `Ctrl+F` opens that search while the pointer or focus is over the panel, and
67
+ pressing it again focuses the open field with the caret after the query.
68
+ - **File history**: a change row's context menu opens that file's commit history
69
+ in the same pane; picking a commit shows that commit's diff for the file, with
70
+ one control back to the history list.
71
+ - **Commit changes**: a commit's context menu opens a review of that commit —
72
+ a filterable file list with per-file `+n/−n` counts and the commit totals;
73
+ opening a file shows its diff for the commit, with one control back to the
74
+ review. Choosing another commit replaces the review in the same pane.
75
+ - **Branches**: every local branch with its upstream and last commit date,
76
+ coloured the way VS Code shows them — green `↑n` for local commits the remote
77
+ does not have, amber `↓n` for remote commits not pulled yet, and a green `▲+`
78
+ unpublished mark for a branch with no upstream. Green is reserved for work that
79
+ has not been pushed; the current branch is marked by a highlighted row, a bold
80
+ name, and a neutral check. Expanding a branch pages its commits, expanding a
81
+ commit lists the files it changed, and clicking one shows that file's diff
82
+ inside the commit.
83
+ - **Remotes**: each remote expands into its remote-tracking branches, which
84
+ expand into commits and changed files exactly like local branches.
85
+ - **Stashes and tags**: the stash stack (with its patch) and tags.
86
+ - **Pending operation banner**: an in-progress cherry pick, revert, merge, or
87
+ rebase is named, with one control to abort it.
88
+
89
+ ## Requirements
90
+
91
+ Git is required. Publishing to GitHub additionally uses the GitHub CLI: install
92
+ `gh` and sign in once (`gh auth login`); the dialog reads the account from the
93
+ CLI and offers private/public destinations for it. Without `gh`, publishing
94
+ still works through a custom remote URL.
95
+ Commit-message generation uses the app's configured default model; a profile
96
+ without a model route reports that generation is unavailable while the rest of
97
+ the panel keeps working.
98
+
99
+ ## What it does
100
+
101
+ - The message field starts one line tall and grows to six lines; ticking
102
+ **Amend** fills it with the previous commit message and unticking restores the
103
+ draft that was there before.
104
+ - Stage, unstage, discard, and commit (including amend). Multi-select works with
105
+ checkboxes, `Ctrl`/`Cmd`-click, and `Shift`-click; while a section has a
106
+ selection its header row shows the count plus the stage/unstage/discard
107
+ commands beside the bulk stage-all command, so the list gains no extra row.
108
+ Clicking empty space in the list clears the selection, a right-click on a
109
+ selected row commands the whole selection (an unselected row is selected
110
+ first), and the list no longer takes text selection. A section with a
111
+ selection shows its total and a parenthesised selection count beside the
112
+ title and keeps no per-selection header controls; the row actions and the
113
+ context menu still apply to the whole selection.
114
+ - The repository header's more-actions menu offers stage all, unstage all,
115
+ discard all, stash all (with untracked), commit all, undo the last commit,
116
+ fetch, pull, and push.
117
+ - Menus, the branch switcher, and dialogs use the host's own surface
118
+ tokens (`--dsw-menu-surface-fill`, `--dsw-menu-backdrop-filter`,
119
+ `--dsw-elevation-prominent`, `--dsw-alias-toast-bg`, the radius and menu-icon
120
+ scales), so their fill, blur, and row geometry match the app's native popovers
121
+ in both themes. The bottom toast card follows the active theme's layered
122
+ surface and label colours, tinted only by its tone colour.
123
+ - Context menus on changes, branches, remote branches, commits, commits' files,
124
+ remotes, stashes, and tags: show changes, preview in this panel, file
125
+ history,
126
+ stage/unstage, discard, stash the selected paths, add to `.gitignore`, copy a
127
+ path or absolute path, reveal in the file manager, check out a branch, check
128
+ out a commit, create/rename/delete a branch, delete a remote branch, copy a
129
+ commit SHA or message, cherry-pick, revert, apply/pop/drop a stash, and delete
130
+ a tag.
131
+ - **Show changes** hands the file to the app's own changes view (`本地变更` /
132
+ `变更请求`, the rich review tab) scrolled to that file, through
133
+ `ctx.sidebarRight.openResource('dsh-resource://forge-changes/<session>/local',
134
+ { params: { path } })`; the comparison pane's hand-off button does the same.
135
+ - Fetch all remotes, pull, and push; a branch with no upstream gets one on push.
136
+ A fetch reports whether remote references actually moved ("no new commits" vs
137
+ "N references updated"), and the remotes header carries the last fetch time
138
+ inline, so freshness costs no extra row.
139
+ Refresh, fetch, pull, push, commit, and branch operations re-read every expanded
140
+ branch's commit list and every expanded commit's files, so refreshed history
141
+ replaces the cached lists instead of leaving stale rows. Branch rows switch
142
+ from their context menu or the header's branch picker; they carry no hover
143
+ checkout button. Branch names follow VS Code's tracking tones: green when the
144
+ branch has unpushed work, amber when it has unpulled commits. Hovering a
145
+ branch that is behind its upstream adds a pull control that fetches and
146
+ fast-forwards exactly that branch (without checking it out); branches with
147
+ nothing to pull show no such control. Committing also offers "commit all changes" and "undo last
148
+ commit".
149
+ - `⌘Enter` / `Ctrl+Enter` commits from the message field.
150
+
151
+ ## Where it appears
152
+
153
+ A branch-glyph button in the Conversation header opens the Source control page in
154
+ the right sidebar; picking **Source control** from the sidebar guide page opens
155
+ the same page. The page's tab chip reads `Source control` and follows the UI
156
+ language.
157
+
158
+ ## How it works
159
+
160
+ The browser half cannot call generated Remotes, so the package carries its own
161
+ JSON route on the shared web server:
162
+
163
+ - `POST /api/dsh-git-scm` with `{ sessionId, action, params }`, answered with
164
+ `{ ok: true, data }` or `{ ok: false, error: { code, message, detail } }`.
165
+ Actions: `summary`, `status`, `diff`, `commits`, `commitFiles`, `commitDiff`,
166
+ `stashDiff`, and `action`.
167
+ - Only same-origin JSON POSTs are admitted. A request names a Session, never a
168
+ path: the Host half resolves the Session's effective working directory through
169
+ the `workingDirectory` service, so a page cannot reach a directory the open
170
+ Session does not already belong to.
171
+ - Reading is lazy: the opening snapshot carries identity, changes, branches,
172
+ stashes, and tags; a branch's commits and a commit's files are read only when
173
+ that tree node expands.
174
+ - Every Git invocation goes through `ctx.subprocess` (executable resolution plus
175
+ a collected spawn) with a fixed prefix that disables hooks, optional index
176
+ writes, and the filesystem monitor. Local commands are bounded at 30 s and
177
+ remote operations (fetch, pull, push, deleting a remote branch) at 300 s.
178
+
179
+ | File | Role |
180
+ |:--|:--|
181
+ | `src/index.ts` | Host half: the JSON route, Session resolution, the subprocess `exec` seam |
182
+ | `src/host/git.ts` | Git command layer: argv construction, machine-output parsing, operations |
183
+ | `src/host/types.ts` | Host-side TypeScript contracts (wire shapes, exec seam, Git results) |
184
+ | `src/client/*.ts(x)` | Browser half sources: panel, trees, menus, diff view, copy, styles |
185
+ | `cordis.patch.yml` | Bundle patch layer; its row `name` equals `package.json#name` |
186
+ | `tests/*.test.ts` | `node:test` suites for the Git layer, the Host route and the UI |
187
+
188
+ ## Install
189
+
190
+ Published to npm, install it into a DSH profile:
191
+
192
+ ```sh
193
+ dsh plugin --profile <profile> add dsh-git-scm
194
+ ```
195
+
196
+ For local development, pack the package and install that tarball (this is the
197
+ closest to the real npm layout):
198
+
199
+ ```sh
200
+ pnpm --filter dsh-git-scm pack
201
+ dsh plugin --profile dev add ./packages/dsh-git-scm/dsh-git-scm-0.1.0.tgz
202
+ ```
203
+
204
+ The bundle patch inserts the Host row, and the `dsh.client` declaration in
205
+ `package.json` makes the Web app load `exports["./client"]`. Restart the Harness
206
+ after installing the Host half; a rebuilt browser bundle is served on the next
207
+ page load.
208
+
209
+ ## Development
210
+
211
+ ```sh
212
+ pnpm install
213
+ pnpm --filter dsh-git-scm build # host (lib/index.js + d.ts) + client (lib/client.js)
214
+ pnpm --filter dsh-git-scm typecheck # strict host config + relaxed client config
215
+ pnpm --filter dsh-git-scm test # builds first, then node:test on tests/*.test.ts
216
+ pnpm --filter dsh-git-scm dev # host watch
217
+ pnpm --filter dsh-git-scm dev:client # browser bundle watch
218
+ ```
219
+
220
+ ## TypeScript port
221
+
222
+ This package is a 1:1 TypeScript port of the JavaScript plugin at
223
+ `<DSH checkout>/.dsh-plugins/dsh-git-scm`; behavior, route shape, Git argv, error
224
+ codes and UI structure are unchanged.
225
+
226
+ - **Host half** (`src/index.ts`, `src/host/git.ts`): strict TypeScript
227
+ (`tsconfig.json`, extends the repo base). The Cordis context services are
228
+ typed through the official DSH type packages listed in `devDependencies`; the
229
+ wire contracts and Git result objects live in `src/host/types.ts`. Node
230
+ builtins are typed by `@types/node`. These packages are **build-time only**:
231
+ Vite externalizes `@deepseek-ai/*` and `node:*`, and `dependencies` stays empty
232
+ because the running DSH profile injects them.
233
+ - **Browser half** (`src/client/*.ts(x)`): converted from JSX with the ESBuild
234
+ JSX factory `h` + `React.Fragment`. `tsconfig.client.json` is intentionally
235
+ relaxed (`strict: false`, DOM lib) for the migrated UI code; `React` is typed
236
+ as `any` because it arrives through the loader factory's `require('react')`.
237
+ - **Build**: `vite.config.ts` emits the host ESM entry plus `lib/index.d.ts`;
238
+ `vite.client.config.ts` emits the classic-IIFE `lib/client.js` that calls
239
+ `window.__ModuleLoader__.load` exactly once. Both are git-ignored build output.
240
+ - **Tests**: `node:test` suites are TypeScript and run through Node's native
241
+ type stripping; the UI suite evaluates the built `lib/client.js` in jsdom with
242
+ React 18.
243
+
244
+ ## Known limitations
245
+
246
+ - One repository per Session: the panel reads the checkout that contains the
247
+ Session's working directory and does not offer a repository picker.
248
+ - No merge, rebase, blame, or history graph; conflicts are shown and can be
249
+ staged after they are resolved outside the panel.
250
+ - Branch lists are capped at 500 local and 500 remote branches.
251
+ - A third-party plugin cannot mount the host's diff component, so the docked
252
+ comparison is this plugin's own renderer (line numbers, collapsed unchanged
253
+ runs, side-by-side mode) styled with the host's theme tokens; the host's real
254
+ changes view is one click away in the comparison header and the context menu.
255
+ - Authentication for push and pull is Git's own (credential helpers, SSH agent);
256
+ the panel never handles tokens.
@@ -0,0 +1,6 @@
1
+ # Bundle patch layer: one Host row loads the package's main entry (the Git HTTP
2
+ # route), and the `dsh.client` declaration in package.json makes the Web app load
3
+ # ./client as this package's browser half (the right-sidebar source-control tab).
4
+ - insert:
5
+ - id: dsh-git-scm
6
+ name: dsh-git-scm
package/icon.svg ADDED
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Git source control">
2
+ <rect width="64" height="64" rx="14" fill="#1F2430"/>
3
+ <path d="M22 16v22" stroke="#E7A94B" stroke-width="4" stroke-linecap="round"/>
4
+ <path d="M22 30c0 8 6 12 14 12h6" stroke="#E7A94B" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
5
+ <circle cx="22" cy="14" r="5" fill="#F6D08A"/>
6
+ <circle cx="22" cy="46" r="5" fill="#F6D08A"/>
7
+ <circle cx="45" cy="42" r="5.5" fill="#7FD1A6"/>
8
+ <path d="M50 16l-2.6 2.6a4 4 0 0 0 0 5.6L50 26.8" stroke="#7FD1A6" stroke-width="3" stroke-linecap="round" fill="none"/>
9
+ <circle cx="46" cy="14" r="2.6" fill="#7FD1A6"/>
10
+ <circle cx="52" cy="22" r="2.6" fill="#7FD1A6"/>
11
+ </svg>