dsh-explorer 0.0.0-stage → 0.1.0

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 {}
+        })
+      }
+    },
+  }
+}

package/src/git-status.ts

@@ -0,0 +1,161 @@
+import { execFile } from 'node:child_process'
+import { existsSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+export interface GitStatusEntry {
+  path: string
+  xy: string
+}
+
+export interface GitStatusResult {
+  isRepo: boolean
+  branch?: string
+  entries: GitStatusEntry[]
+}
+
+const gitCache = new Map<string, { at: number; data: GitStatusResult }>()
+const GIT_CACHE_TTL_MS = 2000
+
+const IGNORED_SCAN_DIRS = new Set([
+  'node_modules',
+  '.agent',
+  '.git',
+  'dist',
+  'target',
+  'build',
+  '.system_generated',
+  '.cache',
+  '.dsh',
+  '.gemini',
+  '.vscode',
+  '.idea',
+])
+
+function parsePorcelainLines(stdout: string, prefix = ''): { branch?: string; entries: GitStatusEntry[] } {
+  let branch: string | undefined
+  const entries: GitStatusEntry[] = []
+
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.replace(/\r$/, '')
+    if (!line) continue
+    if (line.startsWith('## ')) {
+      const branchMatch = line.slice(3).match(/^([^.\s]+)/)
+      if (branchMatch) branch = branchMatch[1]
+      continue
+    }
+    if (line.length < 4) continue
+    const xy = line.slice(0, 2)
+    let p = line.slice(3).trim()
+    if (p.startsWith('"') && p.endsWith('"')) {
+      p = p.slice(1, -1)
+    }
+    // Handle renamed files: "R  old -> new"
+    if (xy.startsWith('R') || xy.endsWith('R')) {
+      const arrowIdx = p.indexOf(' -> ')
+      if (arrowIdx !== -1) {
+        p = p.slice(arrowIdx + 4).trim()
+        if (p.startsWith('"') && p.endsWith('"')) {
+          p = p.slice(1, -1)
+        }
+      }
+    }
+    const cleanPath = p.replace(/\\/g, '/')
+    const finalPath = prefix ? `${prefix.replace(/\\/g, '/').replace(/\/+$/, '')}/${cleanPath}` : cleanPath
+    entries.push({ path: finalPath, xy })
+  }
+
+  return { branch, entries }
+}
+
+function findSubRepos(root: string, depth = 1, maxDepth = 3): string[] {
+  if (depth > maxDepth) return []
+  const repos: string[] = []
+  try {
+    const entries = readdirSync(root, { withFileTypes: true })
+    for (const ent of entries) {
+      if (!ent.isDirectory() || ent.name.startsWith('.') || IGNORED_SCAN_DIRS.has(ent.name)) {
+        continue
+      }
+      const full = join(root, ent.name)
+      if (existsSync(join(full, '.git'))) {
+        repos.push(full)
+      } else {
+        repos.push(...findSubRepos(full, depth + 1, maxDepth))
+      }
+    }
+  } catch {
+    // Ignore read errors
+  }
+  return repos
+}
+
+export async function getGitStatus(cwd: string): Promise<GitStatusResult> {
+  const now = Date.now()
+  const cached = gitCache.get(cwd)
+  if (cached && now - cached.at < GIT_CACHE_TTL_MS) {
+    return cached.data
+  }
+
+  // 1. Try running git directly in cwd
+  try {
+    const { stdout } = await execFileAsync(
+      'git',
+      ['status', '--porcelain', '-b', '-unormal', '--ignored=matching'],
+      { cwd, maxBuffer: 10 * 1024 * 1024, timeout: 3500 }
+    )
+
+    const parsed = parsePorcelainLines(stdout)
+    const data: GitStatusResult = {
+      isRepo: true,
+      branch: parsed.branch,
+      entries: parsed.entries,
+    }
+    gitCache.set(cwd, { at: now, data })
+    return data
+  } catch {
+    // cwd is not a git repo or direct command failed. Check for nested/sub repositories.
+  }
+
+  // 2. Discover sub-repositories within cwd (for workspaces containing multiple repos)
+  try {
+    const subRepos = findSubRepos(cwd)
+    if (subRepos.length > 0) {
+      const allEntries: GitStatusEntry[] = []
+      const subResults = await Promise.all(
+        subRepos.map(async (repoDir) => {
+          const rel = relative(cwd, repoDir).replace(/\\/g, '/')
+          try {
+            const { stdout } = await execFileAsync(
+              'git',
+              ['status', '--porcelain', '-b', '-unormal', '--ignored=matching'],
+              { cwd: repoDir, maxBuffer: 5 * 1024 * 1024, timeout: 3000 }
+            )
+            return parsePorcelainLines(stdout, rel).entries
+          } catch {
+            return []
+          }
+        })
+      )
+
+      for (const res of subResults) {
+        allEntries.push(...res)
+      }
+
+      const data: GitStatusResult = {
+        isRepo: true,
+        entries: allEntries,
+      }
+      gitCache.set(cwd, { at: now, data })
+      return data
+    }
+  } catch {
+    // Ignore
+  }
+
+  const fallback: GitStatusResult = { isRepo: false, entries: [] }
+  gitCache.set(cwd, { at: now, data: fallback })
+  return fallback
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { Config, type ExplorerConfig } from './config.ts'
+import { createFsWatcherServer } from './fs-watch.ts'
+import { listDirectory, listDirectoryBatch } from './fs-tree.ts'
+import { createDirectory, createNewFile, readFileText, removeEntry, renameEntry, writeUpload } from './fs-operations.ts'
+import { getGitStatus } from './git-status.ts'
+import { resolveTarget } from './path-security.ts'
+import { resolveSessionCwd } from './session-path.ts'
+import { readJsonBody, writeError, writeOk, writeJson, ExplorerError } from './wire.ts'
+
+export interface Context {
+  webServer: {
+    register: (options: {
+      path: string
+      kind?: 'exact' | 'prefix'
+      method?: string | string[]
+      prefix?: boolean
+      handler: (req: IncomingMessage, res: ServerResponse) => Promise<boolean | void> | boolean | void
+    }) => () => void
+    registerUpgrade: (options: {
+      path: string
+      prefix?: boolean
+      handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => Promise<boolean | void> | boolean | void
+    }) => () => void
+  }
+  effect: (fn: () => void | (() => void)) => void
+  get: (service: string) => unknown
+}
+
+export const name = 'dsh-explorer'
+export const inject = ['webServer', 'sessions']
+export { Config }
+
+export function apply(ctx: Context, config?: ExplorerConfig): void {
+  const watcher = createFsWatcherServer()
+
+  ctx.effect(() => {
+    return () => {
+      watcher.close()
+    }
+  })
+
+  // WebSocket upgrade
+  ctx.effect(() => {
+    return ctx.webServer.registerUpgrade({
+      path: '/dsh-explorer/api/watch',
+      handler: (req, socket, head) => {
+        watcher.handleUpgrade(req, socket, head)
+        return true
+      },
+    })
+  })
+
+  // HTTP Routes
+  ctx.effect(() => {
+    return ctx.webServer.register({
+      kind: 'prefix',
+      path: '/dsh-explorer/api',
+      handler: async (req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const pathname = url.pathname
+
+        try {
+          if (pathname === '/dsh-explorer/api/events') {
+            const sessionId = url.searchParams.get('sessionId') ?? undefined
+            const cwd = resolveSessionCwd(ctx, sessionId)
+            const dirParam = url.searchParams.get('dir')
+            const targetDir = resolveTarget(cwd, dirParam ?? cwd)
+            watcher.handleSse(req, res, targetDir)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/tree') {
+            const sessionId = url.searchParams.get('sessionId') ?? undefined
+            const cwd = resolveSessionCwd(ctx, sessionId)
+            const dirParam = url.searchParams.get('dir')
+            const targetDir = resolveTarget(cwd, dirParam ?? cwd)
+            const max = config?.maxListingEntries ?? 2000
+            const listing = await listDirectory(targetDir, max)
+            writeOk(res, { listing })
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/batch-tree' && req.method === 'POST') {
+            const body = await readJsonBody<{ paths: string[] }>(req)
+            if (!Array.isArray(body?.paths)) {
+              throw new ExplorerError('bad-request', 'paths must be an array', 400)
+            }
+            const results = await listDirectoryBatch(body.paths)
+            writeOk(res, { results })
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/git-status') {
+            const sessionId = url.searchParams.get('sessionId') ?? undefined
+            const cwd = resolveSessionCwd(ctx, sessionId)
+            const dirParam = url.searchParams.get('dir')
+            const targetDir = resolveTarget(cwd, dirParam ?? cwd)
+            const git = await getGitStatus(targetDir)
+            writeOk(res, { git })
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/read-file') {
+            const pathParam = url.searchParams.get('path')
+            if (!pathParam) {
+              throw new ExplorerError('bad-request', 'missing path parameter', 400)
+            }
+            const data = await readFileText(pathParam)
+            writeOk(res, data)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/new-file' && req.method === 'POST') {
+            const body = await readJsonBody<{ dir: string; name: string }>(req)
+            const created = await createNewFile(body.dir, body.name)
+            writeOk(res, created)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/mkdir' && req.method === 'POST') {
+            const body = await readJsonBody<{ dir: string; name: string }>(req)
+            const created = await createDirectory(body.dir, body.name)
+            writeOk(res, created)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/rename' && req.method === 'POST') {
+            const body = await readJsonBody<{ path: string; newName: string }>(req)
+            const renamed = await renameEntry(body.path, body.newName)
+            writeOk(res, renamed)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/delete' && req.method === 'POST') {
+            const body = await readJsonBody<{ path: string }>(req)
+            await removeEntry(body.path)
+            writeOk(res)
+            return true
+          }
+
+          if (pathname === '/dsh-explorer/api/upload' && req.method === 'POST') {
+            const dirParam = url.searchParams.get('dir')
+            const relParam = url.searchParams.get('relativePath')
+            if (!dirParam || !relParam) {
+              throw new ExplorerError('bad-request', 'dir and relativePath are required', 400)
+            }
+            const uploaded = await writeUpload(dirParam, relParam, req)
+            writeOk(res, uploaded)
+            return true
+          }
+
+          // Unhandled
+          writeJson(res, { ok: false, message: 'Not found' }, 404)
+          return true
+        } catch (err) {
+          writeError(res, err)
+          return true
+        }
+      },
+    })
+  })
+}
+

package/src/path-security.ts

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os'
+import { isAbsolute, normalize, resolve } from 'node:path'
+import { ExplorerError } from './wire.ts'
+
+export function resolveTarget(cwd: string, targetPath: string): string {
+  if (!targetPath) return cwd
+  if (targetPath === '~' || targetPath.startsWith('~/') || targetPath.startsWith('~\\')) {
+    const home = homedir()
+    return normalize(resolve(home, targetPath.slice(targetPath.startsWith('~') ? (targetPath[1] ? 2 : 1) : 0)))
+  }
+  if (isAbsolute(targetPath)) {
+    return normalize(targetPath)
+  }
+  return normalize(resolve(cwd, targetPath))
+}
+
+export function assertSingleSegmentName(name: string): void {
+  if (!name || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+    throw new ExplorerError('bad-request', 'name must be a single path segment without separators', 400)
+  }
+}
+