@qzsy/dsh-workspace-combobox 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qzsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @qzsy/dsh-workspace-combobox
 
-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.
+Workspace combobox plus a Git branch picker for DeepSeek Harness.
+
+## Install
+
+~~~bash
+dsh plugin add @qzsy/dsh-workspace-combobox@0.2.0
+~~~
+
+## Features
+
+### Workspace combobox
+
+The dropdown above the New Session composer becomes a focused search field with
+a keyboard-driven list. One mixed-script query matches workspace names and full
+paths:
+
+- Han characters: 群星
+- full pinyin: qunxing
+- initials: qx
+- English subsequences: flut
+- mixed forms: qunxing-erp, 群erp
+
+Arrow keys move, Enter picks, Escape closes. The panel renders through a React
+portal, like the shipped picker.
+
+<code>Ctrl+.</code> (macOS: <code>⌃.</code>) opens a frame-wide workspace
+switcher over any surface. The command is editable in Settings -> Keyboard
+shortcuts.
+
+### Git branch picker
+
+When the selected workspace is a Git repository, a branch chip appears in the
+New Session hero row, to the right of the agent preset (标准模式):
+
+- shows the current branch, or detached HEAD with the short commit
+- local and remote tabs, each with a count and search
+- current branch is marked
+- selecting a remote branch checks it out as a tracking branch
+- switching shows a spinner in the chip and an animated overlay in the panel;
+  all branch rows are disabled until the operation finishes
+- switching never forces, resets, or discards local changes; Git's own error is
+  shown in the panel when the working tree is dirty
+- a second switch for the same workspace is rejected while one is running
+
+## Where it plugs in
+
+| Surface | Mechanism |
+| --- | --- |
+| New Session workspace dropdown | <code>conversation.hero.workspace</code> occupant at <code>priority: -1</code>; the slot registry renders the lowest priority, shadowing the shipped picker panel. The trigger chip, open state, <code>selectedId</code>, and <code>onPick</code> still come from the conversation owner. |
+| Branch chip beside the agent preset | <code>conversation.hero.options</code> list entry <code>workspace-combobox.branch</code>, after the agent-preset seat. The selected workspace path is shared through a small client store written by the workspace picker. |
+| Frame-wide switcher | <code>shell.overlay</code> entry driven by the <code>workspace.combobox</code> shortcut. |
+| Host capability | Two authenticated <code>/api</code> routes registered on <code>ctx.connection.fetch</code>: <code>/api/workspace-git</code> and <code>/api/workspace-git/switch</code>. |
+
+The browser cannot read Git state by itself, so the Host half runs <code>git</code>
+through <code>execFile</code> (no shell):
+
+- paths must be absolute directories
+- when the Workspace registry is mounted, the path must be one the registry owns
+- switch targets must be present in the latest local or remote listing
+- branch names starting with <code>-</code> or containing whitespace are rejected
+- read timeout is 10s, switch timeout is 60s
+- <code>GIT_TERMINAL_PROMPT=0</code> prevents credential prompts from hanging the plugin
+
+Remote branches are the **local remote-tracking refs** (<code>refs/remotes</code>).
+The plugin does not run <code>git fetch</code>, so the list reflects the last fetch
+and switching is fast and offline-safe.
+
+## Files
+
+- <code>package.json</code> - bundle manifest and <code>dshBuild</code> configuration
+- <code>cordis.patch.yml</code> - inserts the Host row
+- <code>src/index.ts</code> - Host half: Git status/switch routes and path validation
+- <code>runtime/client.js</code> - prebuilt DSH Client module: combobox, branch
+  picker, switcher, shortcut, and the vendored pinyin engine
+- <code>locale/en.json</code>, <code>locale/zh.json</code> - Plugin Manager title and description
+- <code>icon.svg</code> - original artwork
+- <code>vendor/</code> - vendored text-search-engine build and license
+
+## Upstream
+
+The workspace combobox is derived from the local DSH plugin
+<code>dsh-workspace-combobox</code>; the original workspace search and switcher
+remain MIT licensed. The Git branch picker and Host routes are community
+additions.
+
+## Limits
+
+- The workspace trigger chip belongs to the conversation owner and is not
+  replaceable; typing happens inside the opened panel.
+- Remote branch lists use already-fetched remote-tracking refs, not a live
+  network fetch.
+- The branch chip lives in the conversation hero row, so it is visible while
+  the new-session hero is shown.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: workspace-combobox
+      name: '@qzsy/dsh-workspace-combobox'