dsh-gitbar-lite 0.2.1 → 0.4.0

package/README.en.md

@@ -23,7 +23,9 @@ The column is narrow (300px minimum, and a narrow viewport makes it full-screen)
 | Commit | Commits exactly what is ticked — because ticking wrote the index |
 | Commit and Push | Commits, then pushes. **A failed push never claims the commit failed**: the commit happened, and the panel says "committed `abc1234`, but the push failed" |
 | Context button | **Push** when local commits are unpushed, **Publish** when the branch has no upstream, **Fetch** otherwise |
-| Automatic fetch | Every five minutes while the panel is visible and the repository has a remote (`autoFetchMs`, `0` to disable). Failures are silent — no error banner |
+| Fetch before push | A push runs `git fetch --prune` first, then pushes. **Being behind refuses the push** and says by how many — git never merges on a push, so it would be rejected either way, and knowing before the attempt beats being told after. A failed fetch does not block the push |
+| Automatic fetch | GitHub Desktop's rhythm while the panel is visible and the repository has a remote: an hour by default, each tick re-asking whether to run, the next scheduled from the *completion* of the last, with a random skew so panels do not sync up. The pace is `autoFetchMs` (`0` to disable), and "was it fetched recently" is answered by `FETCH_HEAD`'s mtime — so a fetch in a terminal counts too |
+| Panel regains focus | The file list refreshes when the panel becomes visible again; if a script is configured, it runs and fills the Summary |
 | Discard | One file or all of them; the diff is archived *before* anything is restored, and the confirmation offers "delete for good" |
 | Trash | Its own tab. Every discard keeps a diff, recorded **against the commit it was taken from** (`abc1234 initial commit`) |
 | Diff preview | Double-click a file, or a trash entry, to open a diff tab in the column — **one tab, ever**, re-navigated in place |
@@ -127,6 +129,35 @@ The order is fixed and cannot be swapped:
 > **A conflicted file is refused**, with one sentence. Running `git restore` to HEAD in the middle of a merge can
 > disturb the merge state, and that risk is not worth saving a sentence.
 
+### Filling the Summary from a script
+
+Next to the Summary field is a sparkle button — rendered only when a script is configured — that fills the Summary from
+the script's output. It also runs by itself when the panel regains focus: leave the sidebar open, go and let the agent
+work in the conversation, come back, and the Summary is already there.
+
+The script goes in the `summaryScript` config field. It runs with the **repository root as its working directory** and
+is fed nothing on stdin, so "read the top version out of the CHANGELOG" is:
+
+```sh
+grep -m1 '^## ' CHANGELOG.md | sed 's/^## //'
+```
+
+Whatever it prints becomes the Summary. To fill the Description as well, put a line reading `---` in the output:
+everything after it is the Description.
+
+```sh
+echo "1.4.2"
+echo "---"
+echo "Bumped the patch version."
+```
+
+About the shell: on Windows the script prefers Git's own `sh` (so `grep`/`sed`/`awk` work) and puts its `usr/bin` back on
+`PATH` — without that those tools report "command not found". Only a machine with no `sh` at all falls back to
+`cmd.exe`, where the script must be written in cmd syntax. Elsewhere it is plain `sh`.
+
+A failing script does not raise an error banner; its exit code shows as a brief notice, and its stderr is kept verbatim so
+you can judge for yourself.
+
 ## Configuration
 
 | field | default | |
@@ -139,6 +170,7 @@ The order is fixed and cannot be swapped:
 | `trashLimit` | `200` | Trash entries kept; the oldest are dropped along with their diff files |
 | `scanDepth` | `3` | Directory depth the picker scans below the workspace root |
 | `autoFetchMs` | `300000` | How often the panel fetches on its own; `0` disables it, leaving the manual button |
+| `summaryScript` | `""` | A script that fills the Summary. It runs with the repository root as its working directory and whatever it prints becomes the Summary; a line reading `---` starts the Description |
 
 Every field is volatile, so a change on the settings page takes effect without a restart.
 
@@ -192,7 +224,7 @@ are in [`docs/CONTRACT.md`](./docs/CONTRACT.md).
 
 ```sh
 npm test          # unit + real-git e2e + artifact self-check
-npm run test:e2e  # the real-git suite alone (21 sections building their own fixtures, 263 assertions)
+npm run test:e2e  # the real-git suite alone (22 sections building their own fixtures, 277 assertions)
 npm run check     # artifact self-check alone (catches boot-breaking mistakes without restarting DSH)
 npm run test:live # probe a running DSH (not part of npm test; needs the app running)
 ```

package/README.md

@@ -23,7 +23,9 @@ DSH 的右栏本来就是一个常驻的标签区。Git 面板放这里，意味
 | Commit | 只提交勾上的（因为勾选写进了索引） |
 | Commit and Push | 提交后立刻推送；**推送失败不会说「提交失败」**——提交已经发生了，面板会明说「已提交 xxx，但推送失败」 |
 | 上下文按钮 | 有本地未推送提交时是 **Push**，没有上游时是 **Publish**，否则是 **Fetch** |
-| 自动 Fetch | 面板可见且仓库有远端时，每 5 分钟自己 fetch 一次（`autoFetchMs` 可调，`0` 关掉）。失败是静默的，不弹错误 |
+| Push 前先 Fetch | 推送前会先 `git fetch --prune`，然后才推。**已经落后就拒绝推**并说明落后几个——git 的 push 从不合并，早晚都是被拒，先知道比推完再被拒有用。fetch 本身失败不阻断推送 |
+| 自动 Fetch | 面板可见且仓库有远端时按 GitHub Desktop 的口径自己抓：默认 1 小时，每次到点重新判断，下一次从**上一次完成后**开始排，并加随机抖动防止多个面板同步。节奏是 `autoFetchMs`（`0` 关掉），并且用 `FETCH_HEAD` 的 mtime 判断"是不是刚抓过"——你在终端里抓也算 |
+| 面板获得焦点 | 面板重新可见时刷新文件列表；配了脚本就顺带跑一次填 Summary |
 | 舍弃更改 | 单个文件或「全部舍弃」；动手前先把这次改动的 diff 归档，确认框里可以勾「彻底删除」 |
 | 回收站 | 独立 tab。每次舍弃存一份 diff，并记下**是对哪个提交（`abc1234 初始提交`）取的 diff** |
 | diff 预览 | 双击文件，或点回收站里的一条，在右栏开一个 diff 标签页——**永远只占一个**，再点就复用 |
@@ -122,6 +124,28 @@ dsh plugin --profile <你的 profile> remove dsh-gitbar-lite
 
 > **冲突中的文件会被拒绝舍弃**，只给一句提示。在合并中途 `git restore` 到 HEAD 有扰动合并状态的风险，不值得为省一句话去冒。
 
+### 用脚本填 Summary
+
+Summary 输入框旁边有一个星星按钮（只有配了脚本才出现），点一下就把脚本的输出填进去。**侧边栏面板重新获得焦点时也会自动跑一次**——把侧边栏开着，去对话里让 agent 干活，回来，Summary 已经填好了。
+
+脚本写在配置的 `summaryScript` 里，以**仓库根目录为工作目录**运行，不喂任何 stdin。所以「取 CHANGELOG 最顶上的版本号」就是：
+
+```sh
+grep -m1 '^## ' CHANGELOG.md | sed 's/^## //'
+```
+
+输出即 Summary。要同时填 Description，就在输出里单独放一行 `---`，**该行之后**的全部内容是 Description：
+
+```sh
+echo "1.4.2"
+echo "---"
+echo "Bumped the patch version."
+```
+
+关于 shell：Windows 上优先用 Git 自带的 `sh`（`grep`/`sed`/`awk` 都可用），并把它的 `usr/bin` 补回 `PATH`——否则那些工具会「command not found」。机器上没有 `sh` 才退回 `cmd.exe`，那时脚本要按 cmd 语法写。非 Windows 就是 `sh`。
+
+脚本失败不弹错误横幅，退出码会以一条短暂提示显示；它的 stderr 原样保留，方便你自己判断。
+
 ## 配置
 
 | 字段 | 默认 | 说明 |
@@ -134,6 +158,7 @@ dsh plugin --profile <你的 profile> remove dsh-gitbar-lite
 | `trashLimit` | `200` | 回收站保留多少条；超出丢弃最旧的连同它的 diff 文件 |
 | `scanDepth` | `3` | 「不是仓库时」扫描工作区找仓库的目录深度 |
 | `autoFetchMs` | `300000` | 面板自己多久 fetch 一次；`0` = 关掉，只用手动按钮 |
+| `summaryScript` | `""` | 填 Summary 的脚本。以仓库根为工作目录运行，输出即 Summary；单独一行 `---` 之后算 Description |
 
 每个字段都是 volatile 的，所以在设置页改了立刻生效、不用重启。
 
@@ -179,7 +204,7 @@ lib/client.js          浏览器半边：三个 tab 类型 + 面板/回收站/di
 
 ```sh
 npm test          # 单测 + 真 git 的 e2e + 产物自检
-npm run test:e2e  # 只跑真 git 的 e2e（21 个小节，各自造自己的夹具，263 项断言）
+npm run test:e2e  # 只跑真 git 的 e2e（22 个小节，各自造自己的夹具，277 项断言）
 npm run check     # 只用产物自检（不启 DSH 也能发现会让 DSH 起不来的问题）
 npm run test:live # 探测一个正在运行的 DSH（不在 npm test 里，需要跑着应用）
 ```

package/docs/CONTRACT.md

@@ -326,7 +326,7 @@ this package on the next upgrade.
 | state files, the binding key, corruption tolerance, write serialization | `test/store.test.mjs` |
 | the route carrier, single registration under a hostile service order, error classification | `test/index.test.mjs` |
 | every registration identity, the wire literals, the dictionaries, and the hook-free components' rendered trees | `test/client.test.mjs` |
-| the whole host stack against **real git**, mutation by mutation | `test/e2e.mjs`, 263 assertions over 21 sections that build their own fixtures |
+| the whole host stack against **real git**, mutation by mutation | `test/e2e.mjs`, 277 assertions over 22 sections that build their own fixtures |
 | the manifest, the patch layer, the tarball's contents, the two copies of the wire contract, the dictionaries, the workflow | `test/check.mjs` |
 | that the client bundle would not abort the Host boot | `scripts/check-client-bundle.mjs` |
 

package/lib/client.js

@@ -75,6 +75,7 @@ window.__ModuleLoader__.load({
       TRASH_DELETE: 'trashDelete',
       TRASH_CLEAR: 'trashClear',
       TRASH_RESTORE: 'trashRestore',
+      RUN_SCRIPT: 'runScript',
       PREFS: 'prefs',
     }
 
@@ -167,6 +168,7 @@ window.__ModuleLoader__.load({
       'commit.descriptionPlaceholder': 'Description（可选）',
       'commit.expand': '展开 Description',
       'commit.collapse': '收起 Description',
+      'commit.runScript': '用脚本填 Summary',
       'commit.commit': 'Commit',
       'commit.commitAndPush': 'Commit and Push',
       'commit.needsSummary': '先写 Summary',
@@ -251,6 +253,7 @@ window.__ModuleLoader__.load({
       'toast.trashCleared': '回收站已清空（{n} 条）',
       'toast.trashDeleted': '已删除那条记录',
       'toast.trashRestored': '已恢复 {n} 个文件的更改',
+      'toast.scriptFailed': '脚本退出码 {code}',
       'toast.pushFailed': '已提交 {commit}，但推送失败',
     }
 
@@ -298,6 +301,7 @@ window.__ModuleLoader__.load({
       'commit.descriptionPlaceholder': 'Description (optional)',
       'commit.expand': 'Show the Description field',
       'commit.collapse': 'Hide the Description field',
+      'commit.runScript': 'Fill the Summary from the script',
       'commit.commit': 'Commit',
       'commit.commitAndPush': 'Commit and Push',
       'commit.needsSummary': 'Write a Summary first',
@@ -382,6 +386,7 @@ window.__ModuleLoader__.load({
       'toast.trashCleared': 'Trash emptied ({n} entries)',
       'toast.trashDeleted': 'Entry deleted',
       'toast.trashRestored': 'Restored the changes to {n} files',
+      'toast.scriptFailed': 'The script exited with {code}',
       'toast.pushFailed': 'Committed {commit}, but the push failed',
     }
 
@@ -576,6 +581,32 @@ window.__ModuleLoader__.load({
       return t('trash.restoreNoContent')
     }
 
+    /**
+     * Split a script's output into the Summary and the Description.
+     *
+     * Everything it printed is the Summary, so a script that knows nothing about
+     * this still fills the box usefully. A line reading exactly `---` is the one
+     * way to say "the rest is the body": it is three characters a shell script
+     * can print, it cannot collide with prose the way a heading might, and it is
+     * already the separator Markdown and YAML front-matter use.
+     *
+     * @param {string} stdout
+     * @returns {{ summary: string, description: string }}
+     */
+    function splitScriptOutput(stdout) {
+      const text = typeof stdout === 'string' ? stdout : ''
+      const lines = text.split(/\r?\n/)
+      const marker = lines.findIndex((line) => line.trim() === '---')
+      if (marker === -1) {
+        const copy = [...lines]
+        while (copy.length > 0 && copy[copy.length - 1].trim() === '') copy.pop()
+        return { summary: copy.join('\n'), description: '' }
+      }
+      const before = lines.slice(0, marker)
+      while (before.length > 0 && before[before.length - 1].trim() === '') before.pop()
+      return { summary: before.join('\n'), description: lines.slice(marker + 1).join('\n').replace(/^\n+/, '') }
+    }
+
     /** How many of a status payload's files are ticked and commit-ready. */
     function stagedCount(state) {
       if (state === null || !Array.isArray(state.files)) return 0
@@ -756,6 +787,18 @@ window.__ModuleLoader__.load({
       'M2.3 3.6V7.4H6.1',
     ], [])
 
+    /**
+     * The script mark: a sparkle, drawn to the same specification.
+     *
+     * DSH has no "generate" or "wand" glyph to copy, and a chevron would read as
+     * "expand" rather than "fill this in", so this is hand-drawn to match the
+     * house rule (16 box, `stroke` on each path).
+     */
+    const WandGlyph = artwork('0 0 16 16', [
+      'M6.5 2.5L7.6 5.9L11 7L7.6 8.1L6.5 11.5L5.4 8.1L2 7L5.4 5.9Z',
+      'M12.2 9.6L12.8 11.2L14.4 11.8L12.8 12.4L12.2 14L11.6 12.4L10 11.8L11.6 11.2Z',
+    ], [])
+
     /** `IconRefreshOutlineRegular`. */
     const RefreshGlyph = artwork(
       '0 0 16 16',
@@ -1322,37 +1365,56 @@ window.__ModuleLoader__.load({
         [sessionId, tab.signal],
       )
 
-      // Load on mount, and again whenever this tab comes back to the front —
-      // the panel can be looking at a working tree the agent just changed.
+      // Refresh when the panel comes back. This is the behaviour the panel is
+      // asked for, and it is also the one that matters: leave the sidebar open,
+      // go and let the agent work in the conversation, come back — the file list
+      // should already show what changed, and the Summary script should already
+      // have run. `tab.visible` is exactly that transition.
+      //
+      // Note that GitHub Desktop does *not* refresh on window focus (its focus
+      // handler only tracks the resize handle); it refreshes on repository switch
+      // and on an hourly background rhythm. The panel follows Desktop's shape
+      // where Desktop has one, and the user's explicit request here, because a
+      // DSH sidebar lives next to a chat the agent is working in.
       const wasVisible = useRef(false)
       const loadedOnce = useRef(false)
       useEffect(() => {
         const visible = tab.visible !== false
         if (!loadedOnce.current || visible) {
           loadedOnce.current = true
+          const returning = wasVisible.current === false && visible
           wasVisible.current = visible
           // Quiet when there is already something to show, so returning to the
           // tab does not flash the loading state over a list the user recognises.
-          void load({ quiet: state !== null })
+          void load({ quiet: state !== null }).then(() => {
+            // After the list, not before: the script may read the tree, and the
+            // Summary should describe what is on screen.
+            if (returning && hasScript) void runScript()
+          })
         }
-      }, [tab.visible, sessionId, load])
+      }, [tab.visible, sessionId, load, hasScript, runScript])
 
-      // Fetch on a rhythm, unattended, while the panel is actually being looked
-      // at. Three conditions gate it, and each one exists for a reason:
+      // Fetch unattended, in the background, while the panel is being looked at.
+      //
+      // GitHub Desktop's shape (`BackgroundFetcher` in app-store), which this
+      // copies: the interval is long (an hour by default, with a five-minute
+      // floor when the server suggests one), each tick re-asks whether it should
+      // run, the next tick is scheduled from the *completion* of the last one
+      // rather than on a fixed period, and a failure is logged and forgotten.
+      //
+      // Three gates, each with a reason:
       //
       //   * the tab must be visible — a hidden panel has no business touching the
-      //     network every few minutes, and the host may have several sessions;
+      //     network, and the host may have several sessions;
       //   * the repository must have a remote — otherwise `fetch` is a guaranteed
       //     E_NO_REMOTE, and a timer that only ever fails is noise;
       //   * nothing else may be in flight — a user mid-commit must not have an
       //     extra git child appear under them.
       //
-      // A failure is silent. The button stays there, the banner stays quiet, and
-      // the next tick tries again: a fetch that failed once (offline, credential
-      // prompt suppressed) usually succeeds later, and a panel that pops an error
-      // every five minutes for a laptop that was closed is worse than one that
-      // says nothing. Success refreshes the status, which is what moves
-      // ahead/behind and the "last fetch" line.
+      // The "has it been long enough" question is answered by the repository
+      // itself: `lastFetchAt` is the mtime of `.git/FETCH_HEAD`, so a fetch run
+      // in a terminal counts, and a repository the user fetched a minute ago is
+      // left alone however long the panel stays open.
       //
       // The conditions are read through a ref rather than listed as dependencies
       // on purpose: a dependency on `state` would restart the clock on every
@@ -1366,10 +1428,29 @@ window.__ModuleLoader__.load({
         if (autoFetchMs === 0) return undefined
         if (tab.visible === false) return undefined
 
-        const timer = setInterval(() => {
+        const sinceLastFetch = () => {
+          const at = latest.current.state?.lastFetchAt
+          const when = Date.parse(typeof at === 'string' ? at : '')
+          if (!Number.isFinite(when)) return Number.POSITIVE_INFINITY
+          return Date.now() - when
+        }
+
+        // Reschedule from completion, not on a fixed period, so a slow fetch
+        // cannot stack up behind itself. The skew keeps two panels that happened
+        // to open together from fetching in lockstep forever.
+        let timer = null
+        let stopped = false
+        const schedule = () => {
+          if (stopped) return
+          const wait = Math.max(0, autoFetchMs - sinceLastFetch()) + Math.ceil(Math.random() * 30000)
+          timer = setTimeout(tick, wait)
+        }
+        const tick = () => {
           const current = latest.current
-          if (current.busy !== null) return
-          if (!Array.isArray(current.state?.remotes) || current.state.remotes.length === 0) return
+          if (current.busy !== null) return schedule()
+          if (!Array.isArray(current.state?.remotes) || current.state.remotes.length === 0) return schedule()
+          if (sinceLastFetch() < autoFetchMs) return schedule()
+
           void rpc(ACTIONS.FETCH, { sessionId }, tab.signal)
             .then(() => {
               if (alive.current) void load({ quiet: true })
@@ -1377,8 +1458,14 @@ window.__ModuleLoader__.load({
             .catch(() => {
               // Deliberately swallowed: see the note above.
             })
-        }, autoFetchMs)
-        return () => clearInterval(timer)
+            .finally(schedule)
+        }
+
+        schedule()
+        return () => {
+          stopped = true
+          if (timer !== null) clearTimeout(timer)
+        }
       }, [autoFetchMs, tab.visible, tab.signal, sessionId, load])
 
       // The column's refresh shortcut, when it has one.
@@ -1505,6 +1592,14 @@ window.__ModuleLoader__.load({
             setSummary('')
             setDescription('')
             setDescriptionOpen(false)
+            // Clear the "already auto-selected this set" guard, so the
+            // select-by-default rule applies again to whatever is left. GitHub
+            // Desktop's equivalent is that a rebuilt working-directory list has
+            // every new file included; here the same effect comes from letting
+            // the existing rule run once more. A clean tree makes it a no-op,
+            // and a partly-ticked commit leaves the rest ticked, which is what
+            // Desktop does.
+            autoStaged.current = ''
             const short = data.commit?.short ?? ''
             if (andPush && data.push?.ok === false) {
               flash('warn', `${t('toast.pushFailed', { commit: short })}：${errorText(t, data.push.error?.code, data.push.error?.message)}`)
@@ -1516,6 +1611,36 @@ window.__ModuleLoader__.load({
         [run, summary, description, flash, t],
       )
 
+      // The user's own script, run to fill the Summary. Only offered when the
+      // config actually has one, and quiet when it is not configured — a panel
+      // that never sets it should look exactly as it did before this existed.
+      const hasScript = typeof state?.summaryScript === 'string' && state.summaryScript.trim() !== ''
+
+      const runScript = useCallback(async () => {
+        setBusy('script')
+        try {
+          const result = await rpc(ACTIONS.RUN_SCRIPT, { sessionId }, tab.signal)
+          if (!alive.current) return
+          if (result.ran !== true) return
+          const { summary: filled, description: body } = splitScriptOutput(result.stdout)
+          setSummary(filled)
+          if (body !== '') {
+            setDescription(body)
+            setDescriptionOpen(true)
+          }
+          setError(null)
+          if (result.exitCode !== 0) {
+            flash('warn', t('toast.scriptFailed', { code: result.exitCode ?? '?' }))
+          }
+        } catch (failure) {
+          if (alive.current && failure?.name !== 'AbortError') {
+            setError({ code: failure.code ?? 'E_UNKNOWN', message: failure.message })
+          }
+        } finally {
+          if (alive.current) setBusy(null)
+        }
+      }, [sessionId, tab.signal, flash, t])
+
       const runContext = useCallback(() => {
         const action = contextAction(state)
         void run('context', action, undefined, (data) => {
@@ -1705,6 +1830,25 @@ window.__ModuleLoader__.load({
                 if (event.key === 'Enter' && (event.metaKey || event.ctrlKey) && canCommit) commit(false)
               },
             }),
+            // Fills the Summary (and the Description) from the user's script. Only
+            // rendered when there is one, so a panel that never configures it looks
+            // exactly as it did before.
+            hasScript
+              ? h(
+                  'button',
+                  {
+                    key: 'fill',
+                    type: 'button',
+                    className: 'gitbar-disclose',
+                    title: t('commit.runScript'),
+                    'aria-label': t('commit.runScript'),
+                    'data-gitbar-runscript': '',
+                    disabled: busy !== null,
+                    onClick: () => void runScript(),
+                  },
+                  h(WandGlyph, { size: 13 }),
+                )
+              : null,
             h(
               'button',
               {
@@ -2405,6 +2549,7 @@ window.__ModuleLoader__.load({
       formatRelative,
       lastFetchLabel,
       restoreReasonText,
+      splitScriptOutput,
       stagedCount,
       hasConflict,
       contextLabelKey,

package/lib/host/git.js

@@ -137,6 +137,32 @@ export function createGit(ctx, config) {
    */
   async function run(args, options = {}) {
     const executablePath = await executable(options.signal)
+    return spawnCommand(executablePath, args, options, `git ${args[0] ?? ''}`.trim())
+  }
+
+  /**
+   * Run something that is not git, with the same guarantees `run` gives git.
+   *
+   * The user's Summary script is the one caller: it is a shell, not a git
+   * subcommand, so `run` — which always prepends the git executable — cannot
+   * launch it. Everything else about the contract is shared on purpose: the same
+   * timeout, the same abort handling, the same bounded output, the same
+   * environment, and the same "a non-zero exit is data, not a throw" rule.
+   *
+   * @param {readonly string[]} argv the executable and its arguments, in full
+   * @param {object} [options] same as `run`
+   * @returns {Promise<{ exitCode: number | null, stdout: string, stderr: string, truncated: boolean }>}
+   */
+  async function runAny(argv, options = {}) {
+    return spawnCommand(argv[0], argv.slice(1), options, String(argv[0] ?? ''))
+  }
+
+  /**
+   * Spawn one child and collect it. Every launch in this module goes through
+   * here, so there is exactly one place where the timeout, the abort ladder and
+   * the output ceiling are decided.
+   */
+  async function spawnCommand(executablePath, args, options, label) {
     const timeoutMs = Number.isFinite(config.timeoutMs) ? config.timeoutMs : 30000
     // A zero/negative timeout means "no deadline of our own": still pass the
     // caller's signal so an aborted request does not leave a child running.
@@ -164,11 +190,11 @@ export function createGit(ctx, config) {
       })
     } catch (error) {
       // `spawn` refuses a spec it cannot honour *synchronously*: a signal that is
-      // already aborted, or a cwd/env/grace it considers invalid. Neither is a
-      // git verdict, and letting the throw escape would reach the route layer
-      // unclassified -- a generic internal error for a request that was simply
-      // abandoned. Report it the way the asynchronous abort below does.
-      throw new GitFailure(`git ${args[0] ?? ''}`.trim(), {
+      // already aborted, or an argv/cwd/env/grace it considers invalid. Neither is
+      // a verdict about the work, and letting the throw escape would reach the
+      // route layer unclassified -- a generic internal error for a request that
+      // was simply abandoned. Report it the way the asynchronous abort below does.
+      throw new GitFailure(label, {
         exitCode: null,
         stdout: '',
         stderr: abortReason(signal, timeout, timeoutMs) ?? String(error?.message ?? error),
@@ -178,7 +204,7 @@ export function createGit(ctx, config) {
     const outcome = await handle.done
 
     if (signal !== undefined && signal.aborted) {
-      throw new GitFailure(`git ${args[0] ?? ''}`.trim(), { exitCode: null, stdout: '', stderr: abortReason(signal, timeout, timeoutMs) })
+      throw new GitFailure(label, { exitCode: null, stdout: '', stderr: abortReason(signal, timeout, timeoutMs) })
     }
 
     const out = handle.collected.stdout?.readFrom(0) ?? { text: '', lossy: false }
@@ -237,5 +263,5 @@ export function createGit(ctx, config) {
     return toplevel
   }
 
-  return { executable, run, must, repoRootOf, isRepoRoot }
+  return { executable, run, runAny, must, repoRootOf, isRepoRoot }
 }

package/lib/host/repo.js

@@ -199,6 +199,45 @@ async function fetchTimeOf(gitDirResult) {
   }
 }
 
+/** Resolved once per plugin instance: which shell a script is written for. */
+let scriptShell = null
+
+/**
+ * The argv prefix that runs one script string.
+ *
+ * `sh` if the machine has one, and `cmd.exe /d /s /c` otherwise.
+ *
+ * Why the hunt for `sh` and not simply "use it on Unix, cmd on Windows": the
+ * script is text a user types into a settings field, and the shell it is written
+ * in decides whether `grep`, `sed` and `awk` work. Git for Windows ships a full
+ * `usr/bin` beside the git binary — but it does *not* add it to `PATH`, so a bare
+ * `sh` lookup fails on most Windows machines even though one is installed. The
+ * git binary's own location is therefore the place to look: it is the one
+ * executable this plugin is certain exists, and its neighbour `usr/bin/sh.exe`
+ * is the one that has the POSIX tools beside it.
+ *
+ * @param {object} git the runner from `createGit`, for executable resolution
+ * @param {AbortSignal} [signal]
+ * @returns {Promise<readonly string[]>}
+ */
+async function scriptPrefix(git, signal) {
+  if (scriptShell !== null) return scriptShell
+  if (process.platform !== 'win32') {
+    scriptShell = ['sh', '-c']
+    return scriptShell
+  }
+
+  try {
+    const gitPath = await git.executable('git', signal)
+    const candidate = resolve(dirname(dirname(gitPath)), 'usr', 'bin', 'sh.exe')
+    await stat(candidate)
+    scriptShell = [candidate, '-c']
+  } catch {
+    scriptShell = ['cmd.exe', '/d', '/s', '/c']
+  }
+  return scriptShell
+}
+
 /**
  * Build the repository facade for one plugin instance.
  *
@@ -316,6 +355,9 @@ export function createRepo(git, config) {
       // it), so the rhythm it should fetch on travels with the status it is
       // already reading. Zero means "never, on your own".
       autoFetchMs,
+      // ...and so does the script, so the panel can offer the button only when
+      // there is a script to run.
+      summaryScript: typeof config.summaryScript === 'string' ? config.summaryScript : '',
     }
   }
 
@@ -394,8 +436,30 @@ export function createRepo(git, config) {
    * @param {string} repoRoot
    * @param {AbortSignal} [signal]
    */
+  /**
+   * Push the current branch, publishing it when it has no upstream yet.
+   *
+   * A fetch runs first. GitHub Desktop goes further — fetch, then pull, then push
+   * — but a pull rewrites the working tree, and this panel's whole model is that
+   * a tick is the real index: a merge commit appearing under the user between
+   * their tick and their push would quietly invalidate what they selected. So the
+   * fetch is followed by a check instead, and the push is refused with a sentence
+   * when the branch has fallen behind.
+   *
+   * That refusal is the honest outcome, not a limitation: git never merges on
+   * push, so a behind branch is rejected either way. What the fetch buys is that
+   * the answer is known *before* the push attempt, and that the upstream tracking
+   * ref the ahead/behind count is read from is current rather than however stale
+   * it was when the panel opened.
+   *
+   * The fetch itself is best-effort: if it fails (offline, no credential) the
+   * push still goes ahead, because the fetch's failure says nothing about whether
+   * the push can work, and silently refusing to push would be worse.
+   *
+   * @param {string} repoRoot
+   * @param {AbortSignal} [signal]
+   */
   async function push(repoRoot, signal) {
-    const { branch } = await statusOf(repoRoot, signal)
     const remotesResult = await git.run(['remote'], { cwd: repoRoot, signal })
     const remotes =
       remotesResult.exitCode === 0
@@ -406,13 +470,36 @@ export function createRepo(git, config) {
         : []
     const remote = pickRemote(remotes)
 
+    let fetched = false
+    const preFetch = await git.run(['fetch', '--prune', remote], { cwd: repoRoot, signal, maxBytes: 1024 * 1024 })
+    if (preFetch.exitCode === 0) fetched = true
+
+    // Re-read after the fetch: the branch's upstream and its ahead/behind counts
+    // are exactly what the fetch may have changed.
+    const { branch } = await statusOf(repoRoot, signal)
+
+    // Only refuse when we *know* we are behind, which requires both an upstream
+    // and a fetch that actually told us something. Without an upstream this is a
+    // publish, and a failed fetch leaves the counts unknown — neither should be
+    // turned into a refusal.
+    if (fetched && branch.upstream !== null && branch.behind > 0) {
+      const refusal = new RepoError(
+        ERROR_CODES.PUSH_REJECTED,
+        `远端有新提交（落后 ${branch.behind} 个），先 Pull 或 Rebase 再推。`,
+      )
+      // Carried on the error so the route can report "we did look" alongside the
+      // refusal, rather than the caller having to guess whether a fetch happened.
+      refusal.fetched = true
+      throw refusal
+    }
+
     const args =
       branch.upstream === null ? ['push', '--set-upstream', remote, 'HEAD'] : ['push', remote]
     const result = await git.run(args, { cwd: repoRoot, signal, maxBytes: 1024 * 1024 })
     if (result.exitCode !== 0) {
       throw classifyGitFailure({ ...result, message: `git push failed: ${result.stderr.trim()}` })
     }
-    return { remote, published: branch.upstream === null, output: `${result.stdout}${result.stderr}`.trim() }
+    return { remote, published: branch.upstream === null, fetched, output: `${result.stdout}${result.stderr}`.trim() }
   }
 
   /**
@@ -943,5 +1030,59 @@ export function createRepo(git, config) {
     return { restored, skipped }
   }
 
-  return { readStatus, statusOf, setStaged, commit, push, fetch, fileDiff, discard, restore, canRestore, scanRepos }
+  /**
+   * Run the user's Summary script and report what it printed.
+   *
+   * The script is text from the settings page, run with the repository root as
+   * its working directory, so `grep -m1 '^## ' CHANGELOG.md | sed 's/^## //'` is
+   * a valid script. It is handed nothing on stdin: the inputs worth naming in a
+   * commit are files in the tree, and a script that wants the diff can ask git
+   * for it itself.
+   *
+   * A non-zero exit is reported rather than thrown — a script that finds nothing
+   * is an ordinary outcome, and the panel shows its stderr beside the button.
+   *
+   * @param {string} repoRoot
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<{ ran: boolean, exitCode?: number, stdout?: string, stderr?: string }>}
+   */
+  async function runScript(repoRoot, signal) {
+    const script = typeof config.summaryScript === 'string' ? config.summaryScript.trim() : ''
+    if (script === '') return { ran: false }
+
+    const shell = await scriptPrefix(git, signal)
+    // Git for Windows' `sh` is a MinGW program whose tools (`grep`, `sed`, `awk`)
+    // live in its own `usr/bin`, which git does *not* add to PATH — so a script
+    // that uses them finds nothing unless that directory is put back. This is
+    // what git's own `git-bash` wrapper does, and it is the difference between a
+    // script that works and one that reports "grep: command not found".
+    const env =
+      process.platform === 'win32' && shell.length > 0 && shell[0].includes('usr')
+        ? { PATH: `${dirname(shell[0])}${process.env.PATH === undefined ? '' : `;${process.env.PATH}`}` }
+        : {}
+
+    const result = await git.runAny([...shell, script], { cwd: repoRoot, signal, env })
+
+    return {
+      ran: true,
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    }
+  }
+
+  return {
+    readStatus,
+    statusOf,
+    setStaged,
+    commit,
+    push,
+    fetch,
+    fileDiff,
+    discard,
+    restore,
+    canRestore,
+    scanRepos,
+    runScript,
+  }
 }

package/lib/host/routes.js

@@ -261,7 +261,11 @@ export function createHandlers({ ctx, git, repo, store }) {
       try {
         push = { ok: true, ...(await repo.push(repoRoot, request.signal)) }
       } catch (error) {
-        push = { ok: false, error: describeError(error) }
+        // `fetched` is carried out of a refusal because it is the difference
+        // between "the push was rejected, fetch and try again" and "we already
+        // looked, and the branch really is behind" — the same sentence reads very
+        // differently depending on which one it is.
+        push = { ok: false, error: describeError(error), fetched: error?.fetched === true }
       }
 
       const state = await repo.readStatus(repoRoot, request.signal)
@@ -305,6 +309,19 @@ export function createHandlers({ ctx, git, repo, store }) {
       return { repoRoot, diff }
     },
 
+    /**
+     * Run the user's Summary script and hand back what it printed.
+     *
+     * The panel does the splitting, because the protocol is a presentation rule
+     * (`---` separates Summary from Description) rather than anything the
+     * repository needs to know about.
+     */
+    async [ACTIONS.RUN_SCRIPT](payload, request) {
+      const { repoRoot } = await requireRepoRoot(payload, request.signal)
+      const result = await repo.runScript(repoRoot, request.signal)
+      return { repoRoot, ...result }
+    },
+
     async [ACTIONS.TRASH_LIST](payload, request) {
       const workspace = await requireWorkspace(ctx, stringField(payload, 'sessionId'))
       const prefs = await store.readPrefs()

package/lib/index.js

@@ -76,6 +76,16 @@ export const Config = vol(
      * to disable it; the button still works.
      */
     autoFetchMs: z.number().default(300000),
+    /**
+     * A script that fills in the Summary, run with the repository root as its
+     * working directory. Empty means the feature is off.
+     *
+     * Whatever it prints is the Summary; a line reading `---` splits it, so
+     * everything after that line is the Description. Nothing is fed in — the
+     * inputs worth naming in a commit are files in the tree, and a script that
+     * wants the diff can ask git for it.
+     */
+    summaryScript: z.string().default(''),
   }),
 )
 

package/lib/shared.js

@@ -54,6 +54,15 @@ export const ACTIONS = {
    * that happened after the archive was taken.
    */
   TRASH_RESTORE: 'trashRestore',
+  /**
+   * Run the user's summary script and return what it printed.
+   *
+   * The script is the user's own text from the config, run with the repository
+   * root as its working directory. The panel turns its output into a Summary
+   * (and a Description), which is why this returns the output rather than
+   * writing it anywhere itself.
+   */
+  RUN_SCRIPT: 'runScript',
   /** Read or write the small persisted UI preferences. */
   PREFS: 'prefs',
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gitbar-lite",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "A GitHub Desktop-style Git panel for DSH: changed files, tick-to-stage, Summary + Description, Commit and Commit and Push, discard-to-trash, and diff preview, in the built-in right sidebar.",
   "type": "module",
   "license": "MIT",