dsh-explorer 0.0.0-stage → 0.1.1

package/src/fs-operations.ts

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto'
+import { once } from 'node:events'
+import { createWriteStream } from 'node:fs'
+import { access, lstat, mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { invalidateDirectoryCache } from './fs-tree.ts'
+import { assertSingleSegmentName, resolveTarget } from './path-security.ts'
+import { ExplorerError } from './wire.ts'
+
+export async function createNewFile(dirPath: string, name: string): Promise<{ path: string }> {
+  assertSingleSegmentName(name)
+  const fullPath = join(dirPath, name)
+  try {
+    await access(fullPath)
+    throw new ExplorerError('already-exists', `file "${name}" already exists`, 409)
+  } catch (err) {
+    if (err instanceof ExplorerError) throw err
+  }
+  await writeFile(fullPath, '', { flag: 'wx' })
+  invalidateDirectoryCache(dirPath)
+  return { path: fullPath }
+}
+
+export async function createDirectory(dirPath: string, name: string): Promise<{ path: string }> {
+  assertSingleSegmentName(name)
+  const fullPath = join(dirPath, name)
+  try {
+    await access(fullPath)
+    throw new ExplorerError('already-exists', `directory "${name}" already exists`, 409)
+  } catch (err) {
+    if (err instanceof ExplorerError) throw err
+  }
+  await mkdir(fullPath, { recursive: true })
+  invalidateDirectoryCache(dirPath)
+  return { path: fullPath }
+}
+
+export async function renameEntry(targetPath: string, newName: string): Promise<{ oldPath: string; newPath: string }> {
+  assertSingleSegmentName(newName)
+  const parent = dirname(targetPath)
+  const newPath = join(parent, newName)
+  if (targetPath === newPath) return { oldPath: targetPath, newPath }
+
+  try {
+    await access(newPath)
+    throw new ExplorerError('already-exists', `destination "${newName}" already exists`, 409)
+  } catch (err) {
+    if (err instanceof ExplorerError) throw err
+  }
+
+  await rename(targetPath, newPath)
+  invalidateDirectoryCache(parent)
+  return { oldPath: targetPath, newPath }
+}
+
+export async function removeEntry(targetPath: string): Promise<void> {
+  const parent = dirname(targetPath)
+  const st = await lstat(targetPath)
+  if (st.isDirectory()) {
+    await rm(targetPath, { recursive: true, force: true })
+  } else {
+    await unlink(targetPath)
+  }
+  invalidateDirectoryCache(parent)
+}
+
+export async function readFileText(filePath: string, maxBytes = 1024 * 1024 * 2): Promise<{ text: string; size: number }> {
+  const content = await readFile(filePath)
+  if (content.length > maxBytes) {
+    throw new ExplorerError('payload-too-large', `file exceeds max preview limit of ${maxBytes} bytes`, 413)
+  }
+  return {
+    text: content.toString('utf-8'),
+    size: content.length,
+  }
+}
+
+export async function writeUpload(
+  baseDir: string,
+  relativePath: string,
+  streamChunks: AsyncIterable<Buffer | Uint8Array>,
+): Promise<{ path: string; size: number }> {
+  if (!relativePath || relativePath.startsWith('/') || relativePath.startsWith('\\')) {
+    throw new ExplorerError('bad-request', 'relativePath must stay within upload target', 400)
+  }
+  const segments = relativePath.split(/[\\/]/)
+  if (segments.some(p => !p || p === '.' || p === '..')) {
+    throw new ExplorerError('bad-request', 'relativePath contains invalid path traversal segments', 400)
+  }
+  const target = join(baseDir, ...segments)
+  const tmp = join(dirname(target), `.${basename(target)}.dsh-upload-${randomUUID()}.tmp`)
+  await mkdir(dirname(target), { recursive: true })
+
+  const writeStream = createWriteStream(tmp, { flags: 'wx' })
+  let bytes = 0
+
+  try {
+    for await (const chunk of streamChunks) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      bytes += buf.length
+      if (!writeStream.write(buf)) {
+        await once(writeStream, 'drain')
+      }
+    }
+    writeStream.end()
+    await once(writeStream, 'finish')
+    await rename(tmp, target)
+    invalidateDirectoryCache(dirname(target))
+    return { path: target, size: bytes }
+  } catch (err) {
+    writeStream.destroy()
+    try { await unlink(tmp) } catch {}
+    throw err
+  }
+}
+

package/src/fs-search.ts

@@ -0,0 +1,116 @@
+import { readdir } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+export interface SearchMatch {
+  name: string
+  path: string
+  relativePath: string
+  isDir: boolean
+}
+
+export interface SearchResult {
+  query: string
+  matches: SearchMatch[]
+  totalMatches: number
+  truncated: boolean
+}
+
+const IGNORED_SEARCH_DIRS = new Set([
+  'node_modules',
+  '.agent',
+  '.git',
+  'dist',
+  'target',
+  'build',
+  '.system_generated',
+  '.cache',
+  '.dsh',
+  '.gemini',
+  '.vscode',
+  '.idea',
+])
+
+export async function searchDirectory(
+  rootDir: string,
+  query: string,
+  maxResults = 250,
+  includeHidden = false
+): Promise<SearchResult> {
+  const cleanQuery = query.trim().toLowerCase()
+  if (!cleanQuery) {
+    return { query, matches: [], totalMatches: 0, truncated: false }
+  }
+
+  const isExtensionFilter = cleanQuery.startsWith('*.') && cleanQuery.length > 2
+  const extensionTarget = isExtensionFilter ? cleanQuery.slice(1) : ''
+
+  const matches: SearchMatch[] = []
+  let truncated = false
+  let scannedCount = 0
+  const maxScanned = 30000
+
+  const queue: string[] = [rootDir]
+
+  while (queue.length > 0 && matches.length < maxResults && scannedCount < maxScanned) {
+    const currentDir = queue.shift()!
+    let entries
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+
+    for (const ent of entries) {
+      scannedCount++
+      if (scannedCount >= maxScanned) {
+        truncated = true
+        break
+      }
+
+      if (!includeHidden && ent.name.startsWith('.')) {
+        continue
+      }
+
+      const isDirectory = ent.isDirectory()
+      if (isDirectory && IGNORED_SEARCH_DIRS.has(ent.name)) {
+        continue
+      }
+
+      const fullPath = join(currentDir, ent.name)
+      const relPath = relative(rootDir, fullPath).replace(/\\/g, '/')
+      const nameLower = ent.name.toLowerCase()
+      const relLower = relPath.toLowerCase()
+
+      let isMatch = false
+      if (isExtensionFilter) {
+        isMatch = !isDirectory && nameLower.endsWith(extensionTarget)
+      } else {
+        isMatch = nameLower.includes(cleanQuery) || relLower.includes(cleanQuery)
+      }
+
+      if (isMatch) {
+        matches.push({
+          name: ent.name,
+          path: fullPath,
+          relativePath: relPath,
+          isDir: isDirectory,
+        })
+        if (matches.length >= maxResults) {
+          truncated = true
+          break
+        }
+      }
+
+      if (isDirectory) {
+        queue.push(fullPath)
+      }
+    }
+  }
+
+  return {
+    query,
+    matches,
+    totalMatches: matches.length,
+    truncated,
+  }
+}

package/src/fs-tree.ts

@@ -0,0 +1,155 @@
+import { readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { ExplorerError } from './wire.ts'
+
+export interface CompactSegment {
+  name: string
+  path: string
+}
+
+export interface FsEntry {
+  name: string
+  path: string
+  isDir: boolean
+  hidden: boolean
+  isSymlink: boolean
+  broken: boolean
+  compact?: boolean
+  compactName?: string
+  compactPath?: string
+  compactChain?: CompactSegment[]
+}
+
+export interface FsListing {
+  path: string
+  entries: FsEntry[]
+  truncated: boolean
+}
+
+export function compareEntries(a: FsEntry, b: FsEntry): number {
+  if (a.isDir !== b.isDir) return a.isDir ? -1 : 1
+  const la = a.name.toLowerCase()
+  const lb = b.name.toLowerCase()
+  if (la !== lb) return la < lb ? -1 : 1
+  if (a.name === b.name) return 0
+  return a.name < b.name ? -1 : 1
+}
+
+const directoryCache = new Map<string, { at: number; listing: FsListing }>()
+const DIRECTORY_CACHE_TTL_MS = 300
+
+export function invalidateDirectoryCache(_dir?: string): void {
+  directoryCache.clear()
+}
+
+export async function listDirectory(dirPath: string, maxEntries = 2000): Promise<FsListing> {
+  const now = Date.now()
+  const key = `${dirPath}\0${maxEntries}`
+  const cached = directoryCache.get(key)
+  if (cached && now - cached.at < DIRECTORY_CACHE_TTL_MS) {
+    return cached.listing
+  }
+
+  let dirEnts
+  try {
+    dirEnts = await readdir(dirPath, { withFileTypes: true })
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err)
+    throw new ExplorerError('not-found', `cannot read directory "${dirPath}": ${message}`, 404)
+  }
+
+  const entries: FsEntry[] = []
+  const truncated = dirEnts.length > maxEntries
+  const slice = truncated ? dirEnts.slice(0, maxEntries) : dirEnts
+
+  for (const dirent of slice) {
+    const name = dirent.name
+    const fullPath = join(dirPath, name)
+    const isSymlink = dirent.isSymbolicLink()
+    let isDir = dirent.isDirectory()
+    let broken = false
+
+    if (isSymlink) {
+      try {
+        const targetStat = await stat(fullPath)
+        isDir = targetStat.isDirectory()
+      } catch {
+        broken = true
+      }
+    }
+
+    const hidden = name.startsWith('.')
+    let compact = false
+    let compactName: string | undefined = undefined
+    let compactPath: string | undefined = undefined
+    let compactChain: CompactSegment[] | undefined = undefined
+
+    // If it's a directory, resolve single-child directory chains for compact folding
+    if (isDir && !isSymlink) {
+      try {
+        let currPath = fullPath
+        const chain: CompactSegment[] = [{ name, path: fullPath }]
+        let depth = 0
+        while (depth < 6) {
+          const sub = await readdir(currPath, { withFileTypes: true })
+          const visibleSub = sub.filter((s) => !s.name.startsWith('.'))
+          if (visibleSub.length === 1 && visibleSub[0]!.isDirectory() && !visibleSub[0]!.isSymbolicLink()) {
+            const childName = visibleSub[0]!.name
+            currPath = join(currPath, childName)
+            chain.push({ name: childName, path: currPath })
+            depth++
+          } else {
+            break
+          }
+        }
+        if (chain.length > 1) {
+          compact = true
+          compactName = chain.map((c) => c.name).join('/')
+          compactPath = currPath
+          compactChain = chain
+        }
+      } catch {
+        // Ignore read errors for child probe
+      }
+    }
+
+    entries.push({
+      name,
+      path: fullPath,
+      isDir,
+      hidden,
+      isSymlink,
+      broken,
+      compact,
+      compactName,
+      compactPath,
+      compactChain,
+    })
+  }
+
+  entries.sort(compareEntries)
+
+  const listing: FsListing = {
+    path: dirPath,
+    entries,
+    truncated,
+  }
+
+  directoryCache.set(key, { at: now, listing })
+  return listing
+}
+
+export async function listDirectoryBatch(paths: string[], maxEntriesPerDir = 1000): Promise<Record<string, FsListing>> {
+  const result: Record<string, FsListing> = {}
+  await Promise.all(
+    paths.map(async (p) => {
+      try {
+        result[p] = await listDirectory(p, maxEntriesPerDir)
+      } catch {
+        // Individual directory failures don't fail the whole batch
+      }
+    })
+  )
+  return result
+}
+

package/src/fs-watch.ts

@@ -0,0 +1,179 @@
+import { watch, type FSWatcher } from 'node:fs'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { invalidateDirectoryCache } from './fs-tree.ts'
+
+interface Subscriber {
+  send: (data: unknown) => void
+  close: () => void
+}
+
+interface DirWatcher {
+  watcher: FSWatcher
+  subscribers: Set<Subscriber>
+}
+
+const dirWatchers = new Map<string, DirWatcher>()
+
+function normalizeDirPath(d: string): string {
+  return d.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+}
+
+function subscribeToDir(dir: string, subscriber: Subscriber): () => void {
+  const norm = normalizeDirPath(dir)
+  let entry = dirWatchers.get(norm)
+  if (!entry) {
+    try {
+      const watcher = watch(dir, { recursive: true }, (eventType, filename) => {
+        invalidateDirectoryCache()
+        const payload = {
+          event: eventType,
+          filename: filename ? String(filename) : undefined,
+          timestamp: Date.now(),
+        }
+        const current = dirWatchers.get(norm)
+        if (current) {
+          for (const sub of current.subscribers) {
+            try {
+              sub.send(payload)
+            } catch {
+              // ignore individual send failures
+            }
+          }
+        }
+      })
+      entry = { watcher, subscribers: new Set() }
+      dirWatchers.set(norm, entry)
+    } catch (err) {
+      console.warn('[dsh-explorer] recursive watch failed on', dir, err)
+    }
+  }
+
+  if (entry) {
+    entry.subscribers.add(subscriber)
+  }
+
+  return () => {
+    if (entry) {
+      entry.subscribers.delete(subscriber)
+      if (entry.subscribers.size === 0) {
+        try {
+          entry.watcher.close()
+        } catch {}
+        dirWatchers.delete(norm)
+      }
+    }
+  }
+}
+
+export function createFsWatcherServer(): {
+  handleSse: (req: IncomingMessage, res: ServerResponse, dir: string) => void
+  handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => void
+  close: () => void
+} {
+  let wssPromise: Promise<any> | null = null
+
+  const getWss = async () => {
+    if (!wssPromise) {
+      wssPromise = (async () => {
+        try {
+          const wsModule: any = await import('ws')
+          const Server = wsModule.WebSocketServer ?? wsModule.default?.WebSocketServer
+          if (!Server) return null
+
+          const server = new Server({ noServer: true })
+          server.on('connection', (ws: any, req: IncomingMessage) => {
+            const url = new URL(req.url ?? '/', 'http://localhost')
+            const dir = url.searchParams.get('dir')
+            if (!dir) {
+              ws.close(1008, 'missing dir parameter')
+              return
+            }
+
+            const subscriber: Subscriber = {
+              send: (data) => {
+                if (ws.readyState === 1) { // 1 = OPEN
+                  ws.send(JSON.stringify(data))
+                }
+              },
+              close: () => {
+                try { ws.close() } catch {}
+              },
+            }
+
+            const unsubscribe = subscribeToDir(dir, subscriber)
+            ws.on('close', () => {
+              unsubscribe()
+            })
+          })
+          return server
+        } catch {
+          return null
+        }
+      })()
+    }
+    return wssPromise
+  }
+
+  return {
+    handleSse: (req: IncomingMessage, res: ServerResponse, dir: string) => {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+      })
+      res.write(`data: ${JSON.stringify({ type: 'connected', dir, timestamp: Date.now() })}\n\n`)
+
+      const subscriber: Subscriber = {
+        send: (data) => {
+          try {
+            res.write(`data: ${JSON.stringify(data)}\n\n`)
+          } catch {
+            // Socket write failed
+          }
+        },
+        close: () => {
+          try { res.end() } catch {}
+        },
+      }
+
+      const unsubscribe = subscribeToDir(dir, subscriber)
+
+      req.on('close', () => {
+        unsubscribe()
+      })
+    },
+
+    handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+      getWss().then((server) => {
+        if (server) {
+          server.handleUpgrade(req, socket, head, (ws: any) => {
+            server.emit('connection', ws, req)
+          })
+        } else {
+          socket.destroy()
+        }
+      }).catch(() => {
+        socket.destroy()
+      })
+    },
+
+    close: () => {
+      for (const entry of dirWatchers.values()) {
+        for (const sub of entry.subscribers) {
+          sub.close()
+        }
+        try {
+          entry.watcher.close()
+        } catch {}
+      }
+      dirWatchers.clear()
+      if (wssPromise) {
+        wssPromise.then((server) => {
+          try { server?.close() } catch {}
+        })
+      }
+    },
+  }
+}