dsh-gitbar-lite 0.2.0 → 0.3.0

package/README.en.md

@@ -23,6 +23,7 @@ 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 |
 | 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 |
@@ -126,6 +127,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 | |
@@ -137,12 +167,15 @@ The order is fixed and cannot be swapped:
 | `maxFileBytes` | `2097152` | Larger untracked files are listed but not read, archived, or diffed |
 | `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.
 
 **Where state lives**: `<DSH_HOME>/dsh-gitbar-lite/` (falling back to `~/.dsh`) — `bindings.json` (workspace →
-repository), `prefs.json` (the two remembered choices), and `trash/index.json` plus `trash/<id>.diff`. Every write
-goes through a temp file and a rename, so a crash mid-write cannot truncate a file.
+repository), `prefs.json` (the two remembered choices), `trash/index.json` plus `trash/<id>.diff`, and
+`trash/<id>.content.json` (the raw contents a restore needs). Every write goes through a temp file and a rename, so a
+crash mid-write cannot truncate a file.
 
 ## How it works
 

package/README.md

@@ -23,6 +23,7 @@ DSH 的右栏本来就是一个常驻的标签区。Git 面板放这里，意味
 | Commit | 只提交勾上的（因为勾选写进了索引） |
 | Commit and Push | 提交后立刻推送；**推送失败不会说「提交失败」**——提交已经发生了，面板会明说「已提交 xxx，但推送失败」 |
 | 上下文按钮 | 有本地未推送提交时是 **Push**，没有上游时是 **Publish**，否则是 **Fetch** |
+| 自动 Fetch | 面板可见且仓库有远端时，每 5 分钟自己 fetch 一次（`autoFetchMs` 可调，`0` 关掉）。失败是静默的，不弹错误 |
 | 舍弃更改 | 单个文件或「全部舍弃」；动手前先把这次改动的 diff 归档，确认框里可以勾「彻底删除」 |
 | 回收站 | 独立 tab。每次舍弃存一份 diff，并记下**是对哪个提交（`abc1234 初始提交`）取的 diff** |
 | diff 预览 | 双击文件，或点回收站里的一条，在右栏开一个 diff 标签页——**永远只占一个**，再点就复用 |
@@ -121,6 +122,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 原样保留，方便你自己判断。
+
 ## 配置
 
 | 字段 | 默认 | 说明 |
@@ -132,11 +155,14 @@ dsh plugin --profile <你的 profile> remove dsh-gitbar-lite
 | `maxFileBytes` | `2097152` | 比这大的未跟踪文件只列出来，不读内容、不归档、不出 diff |
 | `trashLimit` | `200` | 回收站保留多少条；超出丢弃最旧的连同它的 diff 文件 |
 | `scanDepth` | `3` | 「不是仓库时」扫描工作区找仓库的目录深度 |
+| `autoFetchMs` | `300000` | 面板自己多久 fetch 一次；`0` = 关掉，只用手动按钮 |
+| `summaryScript` | `""` | 填 Summary 的脚本。以仓库根为工作目录运行，输出即 Summary；单独一行 `---` 之后算 Description |
 
 每个字段都是 volatile 的，所以在设置页改了立刻生效、不用重启。
 
 **状态存在哪**：`<DSH_HOME>/dsh-gitbar-lite/`（没有 `DSH_HOME` 就回落 `~/.dsh`）——
-`bindings.json`（工作区 → 仓库）、`prefs.json`（那两个勾选偏好）、`trash/index.json` + `trash/<id>.diff`。
+`bindings.json`（工作区 → 仓库）、`prefs.json`（那两个勾选偏好）、`trash/index.json` + `trash/<id>.diff` +
+`trash/<id>.content.json`（恢复用的原始内容）。
 都是先写临时文件再 rename，所以写到一半崩了也不会把文件截断。
 
 ## 工作原理

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',
@@ -861,8 +904,11 @@ window.__ModuleLoader__.load({
       '.gitbar-status-conflicted{color:var(--dsw-alias-state-error-primary,#b91c1c)}',
       '.gitbar-path{flex:1 1 auto;min-width:0;display:flex;align-items:baseline;gap:0;overflow:hidden}',
       '.gitbar-dir{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;direction:rtl;text-align:left;color:var(--dsw-alias-label-tertiary,#6b7280)}',
-      '.gitbar-sep{flex:none;color:var(--dsw-alias-label-tertiary,#6b7280)}',
-      '.gitbar-name{flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+      // `direction` is inherited, so the rtl above would otherwise reach the
+      // separator (moving the slash to the wrong end) and the file name (right-
+      // aligning it). Both are spelled back to ltr explicitly.
+      '.gitbar-sep{flex:none;direction:ltr;color:var(--dsw-alias-label-tertiary,#6b7280)}',
+      '.gitbar-name{flex:0 1 auto;min-width:0;direction:ltr;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
       '.gitbar-stats{flex:none;display:flex;gap:3px;font-size:10.5px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}',
       '.gitbar-plus{color:var(--dsw-alias-state-success-primary,#15803d)}',
       '.gitbar-minus{color:var(--dsw-alias-state-error-primary,#b91c1c)}',
@@ -1319,20 +1365,108 @@ 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, hasScript, runScript])
+
+      // 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, 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.
+      //
+      // 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
+      // refresh, and a panel the user keeps interacting with would then never
+      // fetch at all.
+      const latest = useRef({ state: null, busy: null })
+      latest.current = { state, busy }
+
+      const autoFetchMs = typeof state?.autoFetchMs === 'number' && state.autoFetchMs > 0 ? state.autoFetchMs : 0
+      useEffect(() => {
+        if (autoFetchMs === 0) return undefined
+        if (tab.visible === false) return undefined
+
+        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 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 })
+            })
+            .catch(() => {
+              // Deliberately swallowed: see the note above.
+            })
+            .finally(schedule)
         }
-      }, [tab.visible, sessionId, load])
+
+        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.
       useEffect(
@@ -1469,6 +1603,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) => {
@@ -1658,6 +1822,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',
               {
@@ -2358,6 +2541,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.
  *
@@ -206,6 +245,13 @@ async function fetchTimeOf(gitDirResult) {
  * @param {object} config resolved plugin config
  */
 export function createRepo(git, config) {
+  /**
+   * How often the panel should fetch on its own, in milliseconds, or 0 for
+   * "never". Resolved once: the value rides along with every status payload,
+   * because a client bundle cannot read the host's config.
+   */
+  const autoFetchMs = Number.isFinite(config.autoFetchMs) && config.autoFetchMs > 0 ? Math.floor(config.autoFetchMs) : 0
+
   /**
    * Identity, branch and working-tree status of one repository.
    *
@@ -305,6 +351,13 @@ export function createRepo(git, config) {
       counts,
       primary,
       lastFetchAt,
+      // The panel cannot read the host's config (a client bundle has no access to
+      // 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 : '',
     }
   }
 
@@ -932,5 +985,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

@@ -305,6 +305,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

@@ -67,6 +67,25 @@ export const Config = vol(
     trashLimit: z.number().default(200),
     /** Directory depth the repository picker scans below the workspace root. */
     scanDepth: z.number().default(3),
+    /**
+     * How often the panel fetches on its own, in milliseconds.
+     *
+     * A fetch only moves remote refs, never the working tree, so it is safe to
+     * do unattended — but it does hit the network and it does write
+     * `.git/FETCH_HEAD`, which is why it is opt-out rather than opt-in. Set to 0
+     * 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.0",
+  "version": "0.3.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",