dsh-git-scm 0.0.0-stage → 0.2.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,279 @@
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; an untracked directory is
46
+ listed as its files, not as one directory row).
47
+ - **Flat list or directory tree**: the staged and working-tree sections open as a
48
+ flat list; the header's view control switches both to a directory tree whose
49
+ folders start expanded and collapse on click. Single-child directory chains
50
+ compact into one `a / b / c` row, the way the Explorer compacts folders, and a
51
+ directory row carries the same hover commands for every file underneath
52
+ (stage/unstage/discard); its changed-file count appears on hover as well. In a
53
+ narrow panel the flat list keeps the file name
54
+ whole and ellipsizes the grey directory suffix instead of hiding it outright;
55
+ the tree keeps its directory rows at any width.
56
+ - **Change lists right under the repository header**: the staged and
57
+ working-tree sections follow the header directly; the header row itself
58
+ carries the refresh, fetch, pull, push, and bulk-action controls, so no
59
+ separate "Changes" group row takes space.
60
+ - **A collapsible Git repositories group** (branches, remotes, stashes, tags)
61
+ whose sections are indented under it; every section collapses on its own and
62
+ the group title carries no counter.
63
+ - **Docked comparison**: clicking a changed file, a commit's file, or a stash
64
+ opens its comparison in a pane that docks below the list by default (a
65
+ draggable divider resizes it and the size is remembered) and can be switched
66
+ to dock on the right, where both the divider and the pane's own left edge
67
+ resize its width (double-clicking a divider restores the default size); the
68
+ divider is a layout-free seam that sits exactly on the pane border and
69
+ highlights on hover, and the dock keeps a 280px minimum while stopping at the
70
+ list's 300px reservation when the panel is wide enough. Rows carry
71
+ old and new line numbers, long unchanged runs collapse to their edges and
72
+ expand on click, the pane switches between single-column and side-by-side
73
+ views, expands to nearly the whole panel, toggles word wrap (the choice
74
+ persists), and searches its content with match highlighting, a match counter,
75
+ and next/previous stepping. `⌘F` /
76
+ `Ctrl+F` opens that search while the pointer or focus is over the panel, and
77
+ pressing it again focuses the open field with the caret after the query.
78
+ - **File history**: a change row's context menu opens that file's commit history
79
+ in the same pane; picking a commit shows that commit's diff for the file, with
80
+ one control back to the history list.
81
+ - **Commit changes**: a commit's context menu opens a review of that commit —
82
+ a filterable file list with per-file `+n/−n` counts and the commit totals;
83
+ opening a file shows its diff for the commit, with one control back to the
84
+ review. Choosing another commit replaces the review in the same pane.
85
+ - **Branches**: every local branch with its upstream and last commit date,
86
+ coloured the way VS Code shows them — green `↑n` for local commits the remote
87
+ does not have, amber `↓n` for remote commits not pulled yet, and a green `▲+`
88
+ unpublished mark for a branch with no upstream. Green is reserved for work that
89
+ has not been pushed; the current branch is marked by a highlighted row, a bold
90
+ name, and a neutral check. Expanding a branch pages its commits, expanding a
91
+ commit lists the files it changed, and clicking one shows that file's diff
92
+ inside the commit.
93
+ - **Remotes**: each remote expands into its remote-tracking branches, which
94
+ expand into commits and changed files exactly like local branches.
95
+ - **Stashes and tags**: the stash stack (with its patch) and tags.
96
+ - **Pending operation banner**: an in-progress cherry pick, revert, merge, or
97
+ rebase is named, with one control to abort it.
98
+
99
+ ## Requirements
100
+
101
+ Git is required. Publishing to GitHub additionally uses the GitHub CLI: install
102
+ `gh` and sign in once (`gh auth login`); the dialog reads the account from the
103
+ CLI and offers private/public destinations for it. Without `gh`, publishing
104
+ still works through a custom remote URL.
105
+ Commit-message generation uses the app's configured default model; a profile
106
+ without a model route reports that generation is unavailable while the rest of
107
+ the panel keeps working.
108
+
109
+ ## What it does
110
+
111
+ - The message field starts one line tall and grows to six lines; ticking
112
+ **Amend** fills it with the previous commit message and unticking restores the
113
+ draft that was there before.
114
+ - Stage, unstage, discard, and commit (including amend). Multi-select works with
115
+ `Ctrl`/`Cmd`-click and `Shift`-click; while a section has a selection its
116
+ header row shows the count plus the stage/unstage/discard commands beside the
117
+ bulk stage-all command, so the list gains no extra row.
118
+ Clicking empty space in the list clears the selection, a right-click on a
119
+ selected row commands the whole selection (an unselected row is selected
120
+ first), and the list no longer takes text selection. A section with a
121
+ selection shows its total and a parenthesised selection count beside the
122
+ title and keeps no per-selection header controls; the row actions and the
123
+ context menu still apply to the whole selection.
124
+ - The repository header's more-actions menu offers stage all, unstage all,
125
+ discard all, stash all (with untracked), commit all, undo the last commit,
126
+ fetch, pull, and push.
127
+ - Menus, the branch switcher, and dialogs use the host's own surface
128
+ tokens (`--dsw-menu-surface-fill`, `--dsw-menu-backdrop-filter`,
129
+ `--dsw-elevation-prominent`, `--dsw-alias-toast-bg`, the radius and menu-icon
130
+ scales), so their fill, blur, and row geometry match the app's native popovers
131
+ in both themes. The bottom toast card follows the active theme's layered
132
+ surface and label colours, tinted only by its tone colour.
133
+ - Context menus on changes, branches, remote branches, commits, commits' files,
134
+ remotes, stashes, and tags: show changes in this panel, file
135
+ history,
136
+ stage/unstage, discard, stash the selected paths, add to `.gitignore`, copy a
137
+ path or absolute path, reveal in the file manager, check out a branch, check
138
+ out a commit, create/rename/delete a branch, delete a remote branch, copy a
139
+ commit SHA or message, cherry-pick, revert, apply/pop/drop a stash, and delete
140
+ a tag.
141
+ - **Open file reuses one preview**: choosing **Open file** from a change row's
142
+ menu hands the file to the app's own code view. The first open splits the
143
+ docked right Sidebar so the change list stays on the left and the preview opens
144
+ on the right; later opens replace that preview tab instead of adding tabs.
145
+ Deleted files cannot be opened; when the pane cannot split (too narrow, or
146
+ already split) the preview opens as another tab in the active pane.
147
+ - Fetch all remotes, pull, and push; a branch with no upstream gets one on push.
148
+ A fetch reports whether remote references actually moved ("no new commits" vs
149
+ "N references updated"), and the remotes header carries the last fetch time
150
+ inline, so freshness costs no extra row.
151
+ Refresh, fetch, pull, push, commit, and branch operations re-read every expanded
152
+ branch's commit list and every expanded commit's files, so refreshed history
153
+ replaces the cached lists instead of leaving stale rows. Branch rows switch
154
+ from their context menu or the header's branch picker; they carry no hover
155
+ checkout button. Branch names follow VS Code's tracking tones: green when the
156
+ branch has unpushed work, amber when it has unpulled commits. Hovering a
157
+ branch that is behind its upstream adds a pull control that fetches and
158
+ fast-forwards exactly that branch (without checking it out); branches with
159
+ nothing to pull show no such control. Committing also offers "commit all changes" and "undo last
160
+ commit".
161
+ - `⌘Enter` / `Ctrl+Enter` commits from the message field.
162
+
163
+ ## Where it appears
164
+
165
+ A branch-glyph button in the Conversation header opens the Source control page in
166
+ the right sidebar; picking **Source control** from the sidebar guide page opens
167
+ the same page. The page's tab chip reads `Source control` and follows the UI
168
+ language.
169
+
170
+ ## How it works
171
+
172
+ The browser half cannot call generated Remotes, so the package carries its own
173
+ JSON route on the shared web server:
174
+
175
+ - `POST /api/dsh-git-scm` with `{ sessionId, action, params }`, answered with
176
+ `{ ok: true, data }` or `{ ok: false, error: { code, message, detail } }`.
177
+ Actions: `summary`, `github`, `commitMessage`, `status`, `commits`,
178
+ `commitFiles`, `commitDiff`, `stashDiff`, `fileHistory`, `diff`, and `action`.
179
+ `github` reads the GitHub CLI account for the publish dialog, `commitMessage`
180
+ asks the configured model to write or improve a message, and `fileHistory`
181
+ pages one file's commit history.
182
+ - Only same-origin JSON POSTs are admitted. A request names a Session, never a
183
+ path: the Host half resolves the Session's effective working directory through
184
+ the `workingDirectory` service, so a page cannot reach a directory the open
185
+ Session does not already belong to.
186
+ - Reading is lazy: the opening snapshot carries identity, changes, branches,
187
+ stashes, and tags; a branch's commits and a commit's files are read only when
188
+ that tree node expands.
189
+ - Every Git invocation goes through `ctx.subprocess` (executable resolution plus
190
+ a collected spawn) with a fixed prefix that disables hooks, optional index
191
+ writes, and the filesystem monitor. Local commands are bounded at 30 s and
192
+ remote operations (fetch, pull, push, deleting a remote branch) at 300 s.
193
+
194
+ | File | Role |
195
+ |:--|:--|
196
+ | `src/index.ts` | Host half: the JSON route, Session resolution, the subprocess `exec` seam |
197
+ | `src/host/git.ts` | Git command layer: argv construction, machine-output parsing, operations |
198
+ | `src/host/commit-message.ts` | Commit-message prompt construction and model-output cleanup |
199
+ | `src/host/types.ts` | Host-side TypeScript contracts (wire shapes, exec seam, Git results) |
200
+ | `src/client/*.ts(x)` | Browser half sources: panel, trees, menus, diff view, copy, styles |
201
+ | `cordis.patch.yml` | Bundle patch layer; its row `name` equals `package.json#name` |
202
+ | `tests/*.test.ts` | `node:test` suites for the Git layer, the Host route and the UI |
203
+
204
+ ## Install
205
+
206
+ Published to npm, install it into a DSH profile:
207
+
208
+ ```sh
209
+ dsh plugin --profile <profile> add dsh-git-scm
210
+ ```
211
+
212
+ For local development, pack the package and install that tarball (this is the
213
+ closest to the real npm layout; replace `<version>` with the `version` in
214
+ `package.json`):
215
+
216
+ ```sh
217
+ pnpm --filter dsh-git-scm pack
218
+ dsh plugin --profile dev add ./packages/dsh-git-scm/dsh-git-scm-<version>.tgz
219
+ ```
220
+
221
+ The bundle patch inserts the Host row, and the `dsh.client` declaration in
222
+ `package.json` makes the Web app load `exports["./client"]`. Restart the Harness
223
+ after installing the Host half; a rebuilt browser bundle is served on the next
224
+ page load.
225
+
226
+ ## Development
227
+
228
+ ```sh
229
+ pnpm install
230
+ pnpm --filter dsh-git-scm build # host (lib/index.js + d.ts) + client (lib/client.js)
231
+ pnpm --filter dsh-git-scm typecheck # strict host config + relaxed client config
232
+ pnpm --filter dsh-git-scm test # builds first, then node:test on tests/*.test.ts
233
+ pnpm --filter dsh-git-scm dev # host watch
234
+ pnpm --filter dsh-git-scm dev:client # browser bundle watch
235
+ ```
236
+
237
+ ## TypeScript port
238
+
239
+ This package began as a 1:1 TypeScript port of the JavaScript `dsh-git-scm`
240
+ plugin bundled with the DSH checkout: at migration time its behavior, route
241
+ shape, Git argv, error codes, and UI structure matched the original. The two are
242
+ no longer identical — since the port this package has added branch publishing to
243
+ a custom remote or a new GitHub repository, repository initialization,
244
+ model-written commit messages, and word wrap in the comparison pane.
245
+
246
+ - **Host half** (`src/index.ts`, `src/host/git.ts`): strict TypeScript
247
+ (`tsconfig.json`, extends the repo base). The Cordis context services are
248
+ typed through the official DSH type packages listed in `devDependencies`; the
249
+ wire contracts and Git result objects live in `src/host/types.ts`. Node
250
+ builtins are typed by `@types/node`. These packages are **build-time only**:
251
+ Vite externalizes `@deepseek-ai/*` and `node:*`, and `dependencies` stays empty
252
+ because the running DSH profile injects them.
253
+ - **Browser half** (`src/client/*.ts(x)`): converted from JSX with the ESBuild
254
+ JSX factory `h` + `React.Fragment`. `tsconfig.client.json` is intentionally
255
+ relaxed (`strict: false`, DOM lib) for the migrated UI code; `React` is typed
256
+ as `any` because it arrives through the loader factory's `require('react')`.
257
+ - **Build**: `vite.config.ts` emits the host ESM entry plus `lib/index.d.ts`;
258
+ `vite.client.config.ts` emits the classic-IIFE `lib/client.js` that calls
259
+ `window.__ModuleLoader__.load` exactly once. Both are git-ignored build output.
260
+ - **Tests**: `node:test` suites are TypeScript and run through Node's native
261
+ type stripping; the UI suite evaluates the built `lib/client.js` in jsdom with
262
+ React 18.
263
+
264
+ ## Known limitations
265
+
266
+ - One repository per Session: the panel reads the checkout that contains the
267
+ Session's working directory and does not offer a repository picker.
268
+ - No merge, rebase, blame, or history graph; conflicts are shown and can be
269
+ staged after they are resolved outside the panel.
270
+ - Branch lists are capped at 500 local and 500 remote branches.
271
+ - A third-party plugin cannot mount the host's diff component, so the docked
272
+ comparison is this plugin's own renderer (line numbers, collapsed unchanged
273
+ runs, side-by-side mode) styled with the host's theme tokens; the host's own
274
+ Changes view remains available from its normal sidebar entry.
275
+ - **Open file tracks its own preview.** The panel replaces the preview tab it
276
+ opened; a tab opened from another entry point is reused only when it already
277
+ shows that file. Closing the preview makes the next open split a fresh pane.
278
+ - Authentication for push and pull is Git's own (credential helpers, SSH agent);
279
+ 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>