@keith9681/dsh-sidebar 0.15.2

package/src/fs-operations.ts

@@ -0,0 +1,99 @@
+/**
+ * Workspace-safe file mutations for the sidebar (the upload route today).
+ *
+ * Every write is lexically confined to the session workspace: the upload
+ * directory is resolved absolute and must sit inside the session cwd, the
+ * relative path is sanitized (absolute paths, '.', '..' and empty segments
+ * are refused), and the final target must stay inside both. Containment is
+ * lexical (no symlink resolution) — a symlinked directory inside the cwd can
+ * redirect writes outside, matching the trust model of the other /sidebar/*
+ * routes. Bytes stream from the request body to a uniquely named temp sibling
+ * and are renamed into place, so a failed, aborted, or oversized upload never
+ * leaves a partial file at the target path.
+ */
+import { randomUUID } from 'node:crypto'
+import { once } from 'node:events'
+import { createWriteStream } from 'node:fs'
+import { mkdir, rename, rm, stat } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import type { SidebarHttpRequest } from './context-types.ts'
+import { isWithin, requireAbsolute } from './fs-tree.ts'
+import { SidebarError } from './wire.ts'
+
+/** Inputs of one upload: the session scope plus the request body stream. */
+export interface WorkspaceUploadInput {
+  /** The session workspace root; target and directory must stay inside it. */
+  cwd: string
+  /** Absolute upload directory chosen by the client (inside `cwd`). */
+  dir: string
+  /** Relative path below `dir` (absolute paths, '.', '..' and empty segments refused). */
+  relativePath: string
+  /** The request body stream (raw bytes). */
+  chunks: AsyncIterable<string | Uint8Array>
+  /** Byte cap; an oversized upload is refused without touching the target. */
+  limit: number
+}
+
+/**
+ * Stream `chunks` into `dir/relativePath` atomically: a uniquely named temp
+ * sibling receives the bytes, then is renamed over the target. The parent
+ * directory is created on demand (recursive), so folder uploads work before
+ * any level exists. The unique temp name keeps concurrent uploads to the same
+ * target independent (each writes and renames its own file; the last rename
+ * wins) and never blocks later uploads after a crashed process.
+ *
+ * @throws SidebarError with a wire code for containment, shape, and size
+ * failures; the temp file is always removed on failure.
+ */
+export async function writeWorkspaceUpload(input: WorkspaceUploadInput): Promise<{ path: string; size: number }> {
+  const { cwd, dir, relativePath, chunks, limit } = input
+  const base = requireAbsolute(dir)
+  if (!isWithin(cwd, base)) {
+    throw new SidebarError('forbidden', 'upload directory escapes the session workspace', 403)
+  }
+  if (relativePath === '' || relativePath.startsWith('/') || relativePath.startsWith('\\')) {
+    throw new SidebarError('bad-request', 'relativePath must stay below the upload directory', 400)
+  }
+  const segments = relativePath.split(/[\\/]/)
+  if (segments.some(part => part === '' || part === '.' || part === '..')) {
+    throw new SidebarError('bad-request', 'relativePath must stay below the upload directory', 400)
+  }
+  const target = join(base, ...segments)
+  if (!isWithin(cwd, target) || !isWithin(base, target)) {
+    throw new SidebarError('forbidden', 'target escapes the session workspace', 403)
+  }
+  const tmp = join(dirname(target), `.${basename(target)}.dsh-upload-${randomUUID()}.tmp`)
+  await mkdir(dirname(target), { recursive: true })
+  const stream = createWriteStream(tmp, { flags: 'wx' })
+  // Resolves once the stream fully closes; created up front so a stream that
+  // already closed (successful end, later failure) cannot leave the wait hanging.
+  const closed = new Promise<void>((resolve) => { stream.once('close', () => resolve()) })
+  let size = 0
+  let streamError: unknown
+  // A permanent 'error' listener keeps a failing disk from crashing the host:
+  // every await below surfaces the failure through the promise chain instead.
+  stream.on('error', (error) => { streamError = error })
+  try {
+    for await (const chunk of chunks) {
+      const buffer = Buffer.from(chunk)
+      size += buffer.length
+      if (size > limit) throw new SidebarError('too-large', `upload exceeds the ${limit} byte limit`, 413)
+      if (!stream.write(buffer)) await once(stream, 'drain')
+      if (streamError !== undefined) throw streamError
+    }
+    await new Promise<void>((resolve, reject) => {
+      stream.end((error?: Error | null) => (error === undefined || error === null ? resolve() : reject(error)))
+    })
+    if (streamError !== undefined) throw streamError
+    await rename(tmp, target)
+    const info = await stat(target)
+    return { path: target, size: info.size }
+  } catch (error) {
+    // Wait for the stream to fully close before unlinking (Windows locks open
+    // files), then remove our own uniquely named temp file.
+    stream.destroy()
+    await closed.catch(() => {})
+    await rm(tmp, { force: true }).catch(() => {})
+    throw error
+  }
+}

package/src/fs-search.ts

@@ -0,0 +1,86 @@
+/**
+ * Recursive file-name search for the editor's merged-mode side panel.
+ * Streams the tree with opendir and matches the query as a case-insensitive
+ * substring of each entry's NAME (paths stay relative to the search root —
+ * the client resolves them against the session cwd). No .gitignore semantics
+ * (this is a name lookup, not a code search), but `.git` directories are
+ * skipped outright (VCS internals are never useful results) and symlink
+ * directories are NOT descended (cycle safety).
+ *
+ * Two performance budgets bound the walk: `maxMatches` (the client renders
+ * the flat list) and `maxVisited` (a runaway tree — a home directory root,
+ * a node_modules forest — must not stall the host). Exceeding either stops
+ * early with `truncated: true`.
+ */
+import { opendir } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+
+/** One search: the relative paths of the matching entries (dirs included so
+ *  the client can hint where matches live) plus the truncation flag. */
+export interface FsSearchResult {
+  matches: string[]
+  truncated: boolean
+}
+
+/** Search budgets (both injectable for tests). */
+export interface FsSearchOptions {
+  /** Row cap of the result list (default 200). */
+  maxMatches?: number
+  /** Total entries visited before the walk gives up (default 100_000). */
+  maxVisited?: number
+}
+
+const DEFAULT_MAX_MATCHES = 200
+const DEFAULT_MAX_VISITED = 100_000
+
+/**
+ * Search `root` recursively for entries whose name contains `query`
+ * (case-insensitive).
+ * @param root - absolute search root.
+ * @param query - the name substring; empty matches nothing.
+ * @param opts - budget overrides (tests).
+ * @returns the matching paths RELATIVE to `root` ('/'-separated), sorted,
+ *  plus whether a budget cut the walk short. An unreadable level is skipped
+ *  (permission errors never fail the whole search).
+ */
+export async function searchFiles(root: string, query: string, opts: FsSearchOptions = {}): Promise<FsSearchResult> {
+  const needle = query.trim().toLowerCase()
+  if (needle === '') return { matches: [], truncated: false }
+  const maxMatches = opts.maxMatches ?? DEFAULT_MAX_MATCHES
+  const maxVisited = opts.maxVisited ?? DEFAULT_MAX_VISITED
+
+  const matches: string[] = []
+  let visited = 0
+  let truncated = false
+
+  const walk = async (dir: string): Promise<void> => {
+    if (truncated) return
+    const level = await opendir(dir).catch(() => undefined)
+    if (level === undefined) return
+    for await (const dirent of level) {
+      visited += 1
+      if (visited > maxVisited) {
+        truncated = true
+        return
+      }
+      // .git is VCS-internal noise: never matched, never descended.
+      if (dirent.isDirectory() && dirent.name === '.git') continue
+      if (dirent.name.toLowerCase().includes(needle)) {
+        matches.push(join(relative(root, dir), dirent.name))
+        if (matches.length >= maxMatches) {
+          truncated = true
+          return
+        }
+      }
+      // Descend real directories only: a symlinked directory may point back
+      // up the tree (cycle).
+      if (dirent.isDirectory() && !dirent.isSymbolicLink()) {
+        await walk(join(dir, dirent.name))
+        if (truncated) return
+      }
+    }
+  }
+  await walk(root)
+  // '/' separators on every platform: the client joins onto the cwd itself.
+  return { matches: matches.sort().map(path => path.split(sep).join('/')), truncated }
+}

package/src/fs-tree.ts

@@ -0,0 +1,158 @@
+/**
+ * Single-level directory listing for the sidebar explorer. Streams the level
+ * with opendir, sorts directories first then names (case-insensitive), and
+ * marks POSIX-hidden entries (dot-prefixed) for dimmed display. Symlinks are
+ * stat'ed once to expose their target kind — a symlink to a directory
+ * expands like a directory — and dangling links are flagged broken. The
+ * probe runs only for entries that are actually symlinks, so levels without
+ * links stay as cheap as before.
+ */
+import { opendir, stat } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { SidebarError } from './wire.ts'
+
+/** One explorer row. */
+export interface SidebarFsEntry {
+  name: string
+  path: string
+  isDir: boolean
+  hidden: boolean
+  /** Whether the row is a symlink; `isDir` then describes the link's target. */
+  isSymlink: boolean
+  /** For symlinks: the target is missing or unreadable (stat failed). */
+  broken: boolean
+}
+
+/** One listed level. */
+export interface SidebarFsListing {
+  path: string
+  entries: SidebarFsEntry[]
+  truncated: boolean
+}
+
+/** Directory-first, case-insensitive name ordering (VSCode explorer order). */
+export function compareEntries(a: SidebarFsEntry, b: SidebarFsEntry): number {
+  if (a.isDir !== b.isDir) return a.isDir ? -1 : 1
+  return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' })
+}
+
+/**
+ * List one directory level.
+ * @param path - absolute directory path.
+ * @param maxEntries - row bound of one level (extra rows flag `truncated`).
+ * @returns the sorted listing.
+ * @throws {SidebarError} fs-error when the level is unreadable or not a directory.
+ */
+export async function listDirectory(path: string, maxEntries = 1000): Promise<SidebarFsListing> {
+  let level
+  try {
+    level = await opendir(path)
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot list "${path}": ${messageOf(error)}`, 400)
+  }
+  const rows: SidebarFsEntry[] = []
+  let overflow = 0
+  try {
+    for await (const dirent of level) {
+      if (rows.length >= maxEntries) {
+        overflow += 1
+        continue
+      }
+      // Platform join: on Windows the level path uses '\' — a hardcoded '/'
+      // would leak mixed separators into every row's path.
+      rows.push({
+        name: dirent.name,
+        path: join(path, dirent.name),
+        isDir: dirent.isDirectory(),
+        isSymlink: dirent.isSymbolicLink(),
+        broken: false,
+        hidden: dirent.name.startsWith('.'),
+      })
+    }
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot list "${path}": ${messageOf(error)}`, 400)
+  }
+  // Probe symlink targets AFTER the readdir stream closes, with bounded
+  // concurrency: a symlink-heavy level (UNC/network targets) would otherwise
+  // serialize up to maxEntries stat calls and stall the explorer. Non-symlink
+  // rows are skipped by the probe, so levels without links stay as cheap as
+  // before.
+  await probeSymlinkTargets(rows)
+  rows.sort(compareEntries)
+  return { path, entries: rows, truncated: overflow > 0 }
+}
+
+/** How many symlink target stats run in flight during one level listing. */
+const SYMLINK_PROBE_CONCURRENCY = 32
+
+/** Probe each symlink row's target once (bounded concurrency, order-preserving). */
+async function probeSymlinkTargets(rows: SidebarFsEntry[], concurrency = SYMLINK_PROBE_CONCURRENCY): Promise<void> {
+  let next = 0
+  const workers = Array.from({ length: Math.min(concurrency, rows.length) }, async () => {
+    for (;;) {
+      const index = next
+      next += 1
+      if (index >= rows.length) return
+      const row = rows[index]!
+      if (!row.isSymlink) continue
+      // stat follows the chain; any failure (missing target, ELOOP, permission)
+      // leaves the row as a broken file-shaped link the editor refuses to read.
+      const info = await stat(row.path).catch(() => undefined)
+      row.isDir = info !== undefined ? info.isDirectory() : row.isDir
+      row.broken = info === undefined
+    }
+  })
+  await Promise.all(workers)
+}
+
+/** The root row label of a listing: the last path segment (or the full path at the filesystem root). */
+export function rootLabel(path: string): string {
+  const base = basename(path)
+  return base !== '' ? base : path
+}
+
+/** Parent of a path, or undefined at the filesystem root (the explorer's "up" target). */
+export function parentOf(path: string): string | undefined {
+  const parent = dirname(path)
+  return parent === path ? undefined : parent
+}
+
+/**
+ * Normalize a caller-supplied path to an absolute, resolved path or throw
+ * fs-error. `path.isAbsolute()` is the OS's own notion of absolute: POSIX
+ * roots (`/...`), Windows drive letters (`C:\...`) and — on win32 — UNC
+ * network shares (`\\server\share\...`); drive-relative forms (`C:foo`)
+ * stay rejected.
+ */
+export function requireAbsolute(path: string): string {
+  if (!isAbsolute(path)) {
+    throw new SidebarError('fs-error', `"${path}" is not an absolute path`, 400)
+  }
+  return resolve(path)
+}
+
+/**
+ * Whether `target` lies under `base` (or equals it), tolerant of separator
+ * style and — on Windows, where the filesystem is case-insensitive — of
+ * letter case. The media route uses this instead of a raw `startsWith` so a
+ * case-mismatched or mixed-separator path can never be misclassified
+ * (e.g. `C:\Users\Me` vs `c:/users/me/file.png`).
+ * @param platform - filesystem semantics; injectable so both branches are
+ * unit-testable on any host.
+ */
+export function isWithin(base: string, target: string, platform: NodeJS.Platform = process.platform): boolean {
+  const norm = (value: string): string => value.replace(/[\\/]+/g, '/').replace(/\/$/, '')
+  const b = norm(base)
+  const t = norm(target)
+  if (platform === 'win32') {
+    const lb = b.toLowerCase()
+    const lt = t.toLowerCase()
+    return lt === lb || lt.startsWith(`${lb}/`)
+  }
+  return t === b || t.startsWith(`${b}/`)
+}
+
+/** Message text of an unknown thrown value. */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/git.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 {
+  /** Short hash (7+ chars, display). */
+  hash: string
+  /** Full 40-char hash (advanced operations: revert / cherry-pick). */
+  hashFull: string
+  subject: string
+  author: string
+  /** ISO 8601 author date (`%ai`), e.g. `2024-01-01 10:00:00 +0800`. */
+  date: string
+  /** Ref decorations (`%D` with --decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+  refs: 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%x1f%H%x1f%D` 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, hashFull, refs] = line.split('\x1f')
+    if (hash === undefined || subject === undefined) continue
+    rows.push({
+      hash,
+      subject,
+      author: author ?? '',
+      date: date ?? '',
+      hashFull: hashFull ?? hash,
+      refs: refs ?? '',
+    })
+  }
+  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'],
+      windowsHide: true,
+      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 repository top level containing `cwd` (`git rev-parse --show-toplevel`). */
+export async function repoRoot(cwd: string): Promise<string> {
+  const out = await runGit(cwd, ['rev-parse', '--show-toplevel'])
+  return out.trim()
+}
+
+/** 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). `--untracked-files=all` lists
+ * the CONTENTS of new directories as individual entries (`?? newdir/a.ts`
+ * rather than a collapsed `?? newdir/`), so every row in the source-control
+ * panel is a real file whose diff tab can load. With `=normal`, git folds a
+ * new folder into one trailing-slash entry that has no diff output and
+ * cannot be read as a file.
+ */
+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=all']),
+  ])
+  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), lazily pageable via skip/count. */
+export async function log(cwd: string, count = 30, skip = 0): Promise<GitLogEntry[]> {
+  const raw = await runGit(cwd, [
+    'log', '-n', String(count), '--skip', String(skip), '--decorate=short',
+    '--pretty=format:%h%x1f%s%x1f%an%x1f%ai%x1f%H%x1f%D',
+  ])
+  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
+  }
+}
+
+/** Full patch text of one commit (`git show` with the commit header suppressed).
+ *  Merge commits show their diff against the first parent (`-m --first-parent`
+ *  is a no-op for regular commits), so a history click always has content. */
+export async function commitDiff(cwd: string, hash: string): Promise<string> {
+  return runGit(cwd, ['show', '--no-ext-diff', '--no-color', '--format=', '-m', '--first-parent', hash])
+}
+
+/** Discard the worktree changes of one path (`git checkout -- <path>`; the index is untouched). */
+export async function discard(cwd: string, path: string): Promise<void> {
+  await runGit(cwd, ['checkout', '--', path])
+}
+
+/** Revert one commit onto the current branch with an auto-generated message. */
+export async function revert(cwd: string, hash: string): Promise<void> {
+  await runGit(cwd, ['revert', '--no-edit', hash])
+}
+
+/** Cherry-pick one commit onto the current branch. */
+export async function cherryPick(cwd: string, hash: string): Promise<void> {
+  await runGit(cwd, ['cherry-pick', hash])
+}