dsh-coding-sidebar 1.0.0

package/src/fs-operations.ts

@@ -0,0 +1,95 @@
+/**
+ * Workspace-safe file mutations for the sidebar (the upload route today).
+ *
+ * Every write is confined to the real session workspace: the upload
+ * directory is resolved absolute and its target is checked through existing
+ * filesystem ancestors, the relative path is sanitized (absolute paths, '.',
+ * '..' and empty segments are refused), and the final target must stay inside
+ * the workspace after symlink resolution. 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 { requireAbsolute } from './fs-tree.ts'
+import { ensureWorkspacePath, ensureWorkspaceWritePath } from './path-security.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)
+  await ensureWorkspacePath(cwd, base)
+  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)
+  const safeTarget = await ensureWorkspaceWritePath(cwd, target)
+  const tmp = join(dirname(safeTarget), `.${basename(safeTarget)}.dsh-upload-${randomUUID()}.tmp`)
+  await mkdir(dirname(safeTarget), { 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, safeTarget)
+    const info = await stat(safeTarget)
+    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,113 @@
+/**
+ * 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 known noise directories
+ * (`.git`, `node_modules`, package-manager stores, build caches) are
+ * skipped outright 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
+ * — 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
+
+/**
+ * Directory names that are never useful filename-search results and would
+ * burn the visit budget before the walk reaches project files. Compared
+ * case-insensitively so `Node_Modules` / `.GIT` stay skipped on every
+ * platform. The directory itself is neither matched nor descended.
+ */
+const SEARCH_SKIP_DIRS = new Set([
+  '.git',
+  'node_modules',
+  '.pnpm-store',
+  '.yarn',
+  '.turbo',
+  '.turbopack',
+  '.next',
+  '.nuxt',
+  '.output',
+  '.cache',
+  '.parcel-cache',
+  'coverage',
+  'dist',
+  'build',
+  'out',
+  '.umi',
+  '.umi-production',
+  '.dumi',
+])
+
+/**
+ * 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
+      }
+      // Dependency / VCS / build-output forests: never matched, never descended.
+      if (dirent.isDirectory() && SEARCH_SKIP_DIRS.has(dirent.name.toLowerCase())) 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)
+}