dsh-better-sidebar 0.10.0

package/src/fs-tree.ts

@@ -0,0 +1,115 @@
+/**
+ * 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
+ * reported as files without probing their target — the explorer shows what
+ * dirent says, keeping the read cheap for arbitrarily large levels.
+ */
+import { opendir } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { SidebarError } from './wire.ts'
+
+/** One explorer row. */
+export interface SidebarFsEntry {
+  name: string
+  path: string
+  isDir: boolean
+  hidden: 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
+      }
+      rows.push({
+        name: dirent.name,
+        // Platform join: on Windows the level path uses '\' — a hardcoded '/'
+        // would leak mixed separators into every row's path.
+        path: join(path, dirent.name),
+        isDir: dirent.isDirectory(),
+        hidden: dirent.name.startsWith('.'),
+      })
+    }
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot list "${path}": ${messageOf(error)}`, 400)
+  }
+  rows.sort(compareEntries)
+  return { path, entries: rows, truncated: overflow > 0 }
+}
+
+/** 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. */
+export function requireAbsolute(path: string): string {
+  if (!path.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(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,236 @@
+/**
+ * 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'],
+      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). */
+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), 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])
+}

package/src/html-route.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure URL vocabulary of the /sidebar/html route (HTML previewer).
+ *
+ * Why path-encoded parameters instead of a query string: the previewed
+ * page resolves its relative assets (./style.css, img/x.png) against the
+ * document URL, and the WHATWG URL algorithm DROPS the query of a
+ * path-relative reference — `/sidebar/html?a=1&path=/a/b/` + `./style.css`
+ * would lose the session scope and the route would reject the asset.
+ * Encoding everything into the URL path keeps relative resolution inside
+ * the same route with every request self-contained:
+ *
+ *   /sidebar/html/<sessionId>/<absolute-path segments, encodeURIComponent'd>
+ *   /sidebar/html/S/Users/me/proj/index.html
+ *     + ./style.css → /sidebar/html/S/Users/me/proj/style.css
+ *   Windows: C:\Users\me\a.html → /sidebar/html/S/C%3A/Users/me/a.html
+ *
+ * This module is intentionally dependency-free (no node imports, no wire
+ * helpers) so the client bundle can import `encodeHtmlUrl` without tripping
+ * the build-time purity gate; the host converts decode failures into
+ * SidebarError responses at the route boundary.
+ */
+
+/** One decoded route reference. */
+export interface HtmlRouteRef {
+  sessionId: string
+  /** Absolute file path (leading slash; Windows drives keep their colon). */
+  path: string
+}
+
+/** Decode outcome: the reference, or a client-error description. */
+export type HtmlDecodeResult =
+  | { ok: true; ref: HtmlRouteRef }
+  | { ok: false; status: 400 | 404; message: string }
+
+/** The route prefix both encoders/decoders agree on. */
+export const HTML_ROUTE_PREFIX = '/sidebar/html/'
+
+/** Build the route URL for one absolute file path (client + tests). */
+export function encodeHtmlUrl(sessionId: string, path: string): string {
+  const segments = path.split(/[\\/]+/).filter(segment => segment !== '')
+  return `${HTML_ROUTE_PREFIX}${encodeURIComponent(sessionId)}/${segments.map(encodeURIComponent).join('/')}`
+}
+
+/**
+ * Decode a route pathname into the session + absolute file path. Rejects
+ * a wrong prefix (404), an empty or double-slash path, malformed percent
+ * encoding, and a missing sessionId or file path (400). The caller still
+ * must bound the decoded path with requireAbsolute + isWithin(cwd) — a
+ * decoded `..` segment resolves outside the cwd and is refused there.
+ */
+export function decodeHtmlUrl(pathname: string): HtmlDecodeResult {
+  if (!pathname.startsWith(HTML_ROUTE_PREFIX)) {
+    return { ok: false, status: 404, message: 'not an html route' }
+  }
+  const rest = pathname.slice(HTML_ROUTE_PREFIX.length)
+  if (rest === '' || rest.includes('//')) {
+    return { ok: false, status: 400, message: 'invalid html route path' }
+  }
+  let segments: string[]
+  try {
+    segments = rest.split('/').map(segment => decodeURIComponent(segment))
+  } catch {
+    return { ok: false, status: 400, message: 'malformed URL encoding' }
+  }
+  const [sessionId, ...pathSegments] = segments
+  if (sessionId === undefined || sessionId === '' || pathSegments.length === 0 || pathSegments.some(segment => segment === '')) {
+    return { ok: false, status: 400, message: 'sessionId and file path are required' }
+  }
+  return { ok: true, ref: { sessionId, path: `/${pathSegments.join('/')}` } }
+}