dsh-better-sidebar: VSCode-like right sidebar plugin for the DSH web GUI

Host half (src/index.ts): /sidebar/api JSON API (session cwd, fs tree/read/ write, git status/diff/stage/commit/branch/log/show), /sidebar/file media route, /sidebar/ws/terminal WebSocket over node-pty; routes share the /api trust fence (Host-header loopback or connection.trustedHosts). Client half (src/client): portal-mounted right panel with a per-session split-pane workbench (recursive row/col splits, draggable dividers, tab drag-move), tab bar with max-width 160px + plus-menu (explorer/git/terminal multi-open rules), lazy file explorer rooted at the session cwd, editable text editor (dirty dot, Ctrl/Cmd+S), image + Markdown preview, xterm terminal with reconnect, and a VSCode-style git panel. Per-session state persists to localStorage (dsh-sidebar:v1:<sessionId>). Intercepts the chat turn-tail produced-files row (priority -1 chain entry) to open files in the sidebar. UI styled with the dsh --dsw-* theme tokens and ui-primitives. Build: tsdown emits the host lib plus the __ModuleLoader__ client bundle (externals = module table words; xterm/css inlined). Tests: 19 unit + smoke specs (pure state/tree/git parsers + real git/fs integration).
2026-08-08 01:02:24 +08:00
parent 4f4e462f98
commit 63e2988ef1
31 changed files with 5807 additions and 0 deletions
@@ -0,0 +1,192 @@
+/**
+ * Git operations for the sidebar source-control panel. Everything goes
+ * through the system `git` binary spawned per request (no library, no state),
+ * with porcelain-parseable output formats (`-z` NUL framing, unit separators)
+ * so parsing never depends on locale or color config. All commands run with
+ * `-C <cwd>` on the session's working directory and `--no-pager` /
+ * `-c color.ui=false` so output stays machine-readable.
+ *
+ * Commits use the user's git global identity untouched (never sets
+ * user.name/user.email).
+ */
+import { spawn } from 'node:child_process'
+
+/** A parsed `git status --porcelain=v1 -z` entry. */
+export interface GitStatusEntry {
+  path: string
+  /** Two-letter index/worktree status (X Y), e.g. 'M ', ' M', 'A ', '??'. */
+  xy: string
+}
+
+/** The source-control panel snapshot. */
+export interface GitStatusResult {
+  isRepo: boolean
+  branch?: string
+  entries: GitStatusEntry[]
+}
+
+/** One `git log` row. */
+export interface GitLogEntry {
+  hash: string
+  subject: string
+  author: string
+  date: string
+}
+
+/** One git failure (stderr text as the message). */
+export class GitCommandError extends Error {
+  constructor(
+    message: string,
+    readonly code = 'git-error',
+    readonly command: string,
+  ) {
+    super(message)
+  }
+}
+
+/** Parse porcelain v1 -z output into entries (rename/copy pairs collapse to one row). */
+export function parsePorcelainZ(output: string): GitStatusEntry[] {
+  const tokens = output.split('\0')
+  const entries: GitStatusEntry[] = []
+  let index = 0
+  while (index < tokens.length) {
+    const token = tokens[index]!
+    index += 1
+    if (token === '') continue
+    const xy = token.slice(0, 2)
+    const rest = token.slice(3)
+    entries.push({ path: rest, xy })
+    // Rename/copy entries carry the ORIGIN path as the next NUL field; the
+    // new path (the file as it exists now) is the display path.
+    if ((xy[0] === 'R' || xy[0] === 'C') && tokens[index] !== undefined && tokens[index] !== '') {
+      index += 1
+    }
+  }
+  return entries
+}
+
+/** Parse `git log --pretty=format:%h%x1f%s%x1f%an%x1f%ai` rows. */
+export function parseLogLines(output: string): GitLogEntry[] {
+  const rows: GitLogEntry[] = []
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+    const [hash, subject, author, date] = line.split('\x1f')
+    if (hash === undefined || subject === undefined) continue
+    rows.push({ hash, subject, author: author ?? '', date: date ?? '' })
+  }
+  return rows
+}
+
+/** Run one git command; resolves with stdout, rejects with GitCommandError. */
+function runGit(cwd: string, args: string[], timeoutMs = 30_000): Promise<string> {
+  const full = ['-C', cwd, '--no-pager', '-c', 'color.ui=false', ...args]
+  return new Promise<string>((resolvePromise, reject) => {
+    const child = spawn('git', full, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+    })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new GitCommandError(`git ${args[0] ?? ''} timed out after ${timeoutMs}ms`, 'git-error', args.join(' ')))
+    }, timeoutMs)
+    child.stdout.on('data', (chunk: Buffer) => { stdout += chunk.toString('utf8') })
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') })
+    child.on('error', (error) => {
+      clearTimeout(timer)
+      reject(new GitCommandError(`cannot run git: ${error.message}`, 'git-error', args.join(' ')))
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (code === 0) {
+        resolvePromise(stdout)
+      } else {
+        reject(new GitCommandError(stderr.trim() || `git exited with ${String(code)}`, 'git-error', args.join(' ')))
+      }
+    })
+  })
+}
+
+/** Whether the directory is inside a git work tree (exit-0 `git rev-parse`). */
+export async function isGitRepo(cwd: string): Promise<boolean> {
+  try {
+    const out = await runGit(cwd, ['rev-parse', '--is-inside-work-tree'])
+    return out.trim() === 'true'
+  } catch {
+    return false
+  }
+}
+
+/** The current branch name (`git rev-parse --abbrev-ref HEAD`; 'HEAD' when detached). */
+export async function currentBranch(cwd: string): Promise<string> {
+  const out = await runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  return out.trim()
+}
+
+/** Working-tree status (untracked included). */
+export async function status(cwd: string): Promise<GitStatusResult> {
+  const repo = await isGitRepo(cwd)
+  if (!repo) return { isRepo: false, entries: [] }
+  const [branch, raw] = await Promise.all([
+    currentBranch(cwd).catch(() => 'HEAD'),
+    runGit(cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']),
+  ])
+  return { isRepo: true, branch, entries: parsePorcelainZ(raw) }
+}
+
+/** Diff text of the worktree (unstaged) or the index (staged). */
+export async function diff(cwd: string, path: string | undefined, staged: boolean): Promise<string> {
+  const args = ['diff', '--no-ext-diff', '--no-color', '-U3']
+  if (staged) args.push('--cached')
+  if (path !== undefined) args.push('--', path)
+  return runGit(cwd, args)
+}
+
+/** Stage paths (all when path is undefined). */
+export async function stage(cwd: string, path: string | undefined): Promise<void> {
+  await runGit(cwd, ['add', '-A', ...(path !== undefined ? ['--', path] : [])])
+}
+
+/** Unstage paths (all when path is undefined). */
+export async function unstage(cwd: string, path: string | undefined): Promise<void> {
+  await runGit(cwd, ['reset', '-q', ...(path !== undefined ? ['--', path] : [])])
+}
+
+/** Commit the staged changes with a message (global identity untouched). */
+export async function commit(cwd: string, message: string): Promise<void> {
+  await runGit(cwd, ['commit', '-m', message])
+}
+
+/** Branch names (current first). */
+export async function branches(cwd: string): Promise<{ current: string; names: string[] }> {
+  const [current, raw] = await Promise.all([
+    currentBranch(cwd).catch(() => 'HEAD'),
+    runGit(cwd, ['for-each-ref', '--format=%(refname:short)', 'refs/heads']),
+  ])
+  const names = raw.split('\n').filter(line => line !== '')
+  return { current, names: names.includes(current) ? names : [current, ...names] }
+}
+
+/** Switch to an existing branch. */
+export async function checkout(cwd: string, branch: string): Promise<void> {
+  await runGit(cwd, ['checkout', branch])
+}
+
+/** Recent commit history (newest first). */
+export async function log(cwd: string, count = 30): Promise<GitLogEntry[]> {
+  const raw = await runGit(cwd, ['log', `-n ${count}`, '--pretty=format:%h%x1f%s%x1f%an%x1f%ai'])
+  return parseLogLines(raw)
+}
+
+/**
+ * Content of a file at a revision (`git show <rev>:<path>`), or null when the
+ * revision has no such path (a new/untracked file has no HEAD side).
+ */
+export async function show(cwd: string, rev: string, path: string): Promise<string | null> {
+  try {
+    return await runGit(cwd, ['show', `${rev}:${path}`])
+  } catch {
+    return null
+  }
+}