dsh-scratch-workspace 0.0.0-stage → 0.1.0

package/lib/gc.js

@@ -0,0 +1,221 @@
+/**
+ * Disk Cleanliness (磁盘常态洁净): Lifecycle garbage collection for ephemeral
+ * session directories, empty abandoned folders, and orphan directories.
+ * @module dsh-scratch-workspace/lib/gc
+ */
+
+import { readdir, rename, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { SESSION_DIR_PATTERN } from './isolate.js'
+
+/** Default TTL for orphan session directories: 24 hours. */
+export const DEFAULT_ORPHAN_TTL_MS = 24 * 60 * 60 * 1000
+
+/** Grace period for empty abandoned session folders: 5 minutes. */
+export const EMPTY_SESSION_GRACE_MS = 5 * 60 * 1000
+
+/**
+ * Check whether a directory is empty (ignoring system artifacts like .DS_Store).
+ * @param dir - absolute directory path.
+ * @returns true if directory contains no meaningful files.
+ */
+export async function isDirectoryEmpty(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true })
+    const meaningful = entries.filter(e => e.name !== '.DS_Store' && e.name !== 'Thumbs.db')
+    return meaningful.length === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Remove one session directory safely.
+ * @param sessionDir - absolute path of session directory.
+ */
+export async function removeSessionDir(sessionDir) {
+  try {
+    await rm(sessionDir, { recursive: true, force: true })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Normalize session ID to its 8-char short prefix for directory matching.
+ * @param id - full session ID (e.g. "session-de59473b-0408-...")
+ * @returns 8-character hex prefix
+ */
+export function shortSessionId(id) {
+  const flattened = String(id).replace(/^session-/, '').replaceAll('-', '')
+  return flattened.slice(0, 8).toLowerCase()
+}
+
+/**
+ * Scan isolating roots and clean up orphan and empty abandoned session folders.
+ * @param options - execution parameters.
+ * @returns summary of cleaned directories.
+ */
+export async function cleanOrphans({
+  roots = [],
+  knownSessionIds = new Set(),
+  orphanTtlMs = DEFAULT_ORPHAN_TTL_MS,
+  emptyGraceMs = EMPTY_SESSION_GRACE_MS,
+  now = Date.now(),
+  logger,
+} = {}) {
+  const cleaned = []
+  const knownShortIds = new Set([...knownSessionIds].map(shortSessionId))
+  let scannedCount = 0
+
+  for (const root of roots) {
+    let entries = []
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    scannedCount += entries.length
+
+    // Index titled folders in this root: shortId -> titledDirPath
+    const titledFolders = new Map()
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const match = entry.name.match(SESSION_DIR_PATTERN)
+      if (match && match[1]) {
+        const short = match[2].split('-')[0].toLowerCase()
+        titledFolders.set(short, join(root, entry.name))
+      }
+    }
+
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) {
+        const match = entry.name.match(SESSION_DIR_PATTERN)
+        if (match) {
+          const linkPath = join(root, entry.name)
+          await rm(linkPath, { force: true }).catch(() => {})
+          cleaned.push({ path: linkPath, reason: 'legacy-symlink' })
+          logger?.info?.(`dsh-scratch-workspace gc: removed legacy symlink ${linkPath}`)
+          continue
+        }
+      }
+      if (!entry.isDirectory()) continue
+      const match = entry.name.match(SESSION_DIR_PATTERN)
+      if (!match) continue
+
+      const dirPath = join(root, entry.name)
+      const folderShort = (match[2] ?? match[1] ?? '').split('-')[0].toLowerCase()
+
+      try {
+        // Case 0: Pre-rename duplicate leftover whose titled folder already exists
+        if (!match[1] && titledFolders.has(folderShort)) {
+          const titledDir = titledFolders.get(folderShort)
+          try {
+            const subEntries = await readdir(dirPath)
+            for (const sub of subEntries) {
+              if (sub === '.DS_Store' || sub === 'Thumbs.db') continue
+              await rename(join(dirPath, sub), join(titledDir, sub)).catch(() => {})
+            }
+          } catch {}
+          await removeSessionDir(dirPath)
+          cleaned.push({ path: dirPath, reason: 'pre-rename-duplicate' })
+          logger?.info?.(`dsh-scratch-workspace gc: removed pre-rename duplicate dir ${dirPath}`)
+          continue
+        }
+
+        const info = await stat(dirPath)
+        const ageMs = now - info.mtimeMs
+
+        // Case 1: Empty abandoned session folder past grace period
+        const empty = await isDirectoryEmpty(dirPath)
+        if (empty && ageMs >= emptyGraceMs) {
+          await removeSessionDir(dirPath)
+          cleaned.push({ path: dirPath, reason: 'empty-abandoned' })
+          logger?.info?.(`dsh-scratch-workspace gc: removed empty session dir ${dirPath}`)
+          continue
+        }
+
+        // Case 2: Orphan session directory no longer associated with any session
+        const hasSession = knownShortIds.has(folderShort)
+        if (!hasSession && ageMs > orphanTtlMs) {
+          await removeSessionDir(dirPath)
+          cleaned.push({ path: dirPath, reason: 'orphan-ttl' })
+          logger?.info?.(`dsh-scratch-workspace gc: removed orphan session dir ${dirPath}`)
+        }
+      } catch {
+        // Ignore races with active filesystem operations
+      }
+    }
+  }
+
+  cleaned.cleanedCount = cleaned.length
+  cleaned.scannedCount = scannedCount
+  return cleaned
+}
+
+/**
+ * Setup automatic periodic GC.
+ * @param ctx - Cordis context.
+ * @param iso - shared isolation state.
+ * @param options - GC interval and TTL configuration.
+ * @returns disposer function.
+ */
+export function setupAutoGc(ctx, iso, {
+  intervalMs = 30 * 60 * 1000,
+  orphanTtlMs = DEFAULT_ORPHAN_TTL_MS,
+} = {}) {
+  let timer = null
+
+  async function collectKnownSessions() {
+    const ids = new Set()
+    // Live sessions from registry
+    const registry = ctx.root?.workspaceRegistry ?? ctx.workspaceRegistry
+    const workspaces = registry?.list?.() ?? []
+    for (const ws of workspaces) {
+      for (const id of ws.sessionIds ?? []) ids.add(id)
+    }
+    // Live agents
+    const agents = ctx.agents ?? ctx.root?.agents
+    if (typeof agents?.list === 'function') {
+      for (const ag of agents.list() ?? []) if (ag?.id) ids.add(ag.id)
+    }
+    // Stored headers if available
+    try {
+      const stored = await registry?.listStoredHeaders?.()
+      if (Array.isArray(stored)) {
+        for (const h of stored) if (h?.id) ids.add(h.id)
+      }
+    } catch {}
+
+    return ids
+  }
+
+  async function triggerGc() {
+    try {
+      const known = await collectKnownSessions()
+      const roots = iso.roots()
+      await cleanOrphans({
+        roots,
+        knownSessionIds: known,
+        orphanTtlMs,
+        logger: ctx.logger,
+      })
+    } catch (error) {
+      ctx.logger?.warn?.(`dsh-scratch-workspace gc failed: ${error?.message ?? error}`)
+    }
+  }
+
+  // Initial GC after host settles (10 seconds)
+  const initialTimeout = setTimeout(triggerGc, 10_000)
+  initialTimeout?.unref?.()
+
+  // Periodic GC
+  timer = setInterval(triggerGc, intervalMs)
+  timer?.unref?.()
+
+  return () => {
+    clearTimeout(initialTimeout)
+    if (timer) clearInterval(timer)
+  }
+}

package/lib/isolate.js

@@ -0,0 +1,164 @@
+/**
+ * Isolation policy: which directories isolate their sessions, and where one
+ * session's private directory lands.
+ *
+ * The durable marker is a per-directory `.dsh-isolate` file. In addition,
+ * default-workspace can be automatically isolated to keep ad-hoc explorations
+ * clean without manual intervention.
+ * @module dsh-scratch-workspace/lib/isolate
+ */
+
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises'
+import { join, resolve, sep } from 'node:path'
+
+/** Marker file that switches one directory to per-session working folders. */
+export const MARKER_NAME = '.dsh-isolate'
+
+/** Prefix of every per-session working directory. */
+export const SESSION_DIR_PREFIX = 'session-'
+
+/** Regex matching session directory names, supporting both raw shortIds and titled formats. */
+export const SESSION_DIR_PATTERN = /^session-(?:(.*)-)?([0-9a-fA-F]{8,36}(?:-\d+)?)$/
+
+/**
+ * Sanitize a human session title for filesystem folder naming.
+ * Strips path separators, illegal filename characters, and limits length.
+ * @param {string} title
+ * @param {number} [maxChars=30]
+ * @returns {string}
+ */
+export function sanitizeTitleForPath(title, maxChars = 30) {
+  if (typeof title !== 'string') return ''
+  const cleaned = title
+    .replace(/[\/\\:*?"<>|#\x00-\x1f]/gu, '')
+    .replace(/\s+/gu, '-')
+    .replace(/-+/gu, '-')
+    .trim()
+  return cleaned.slice(0, maxChars).replace(/^-+|-+$/g, '')
+}
+
+/**
+ * Whether a session title is meaningful (not a default placeholder).
+ * @param {string} title
+ * @returns {boolean}
+ */
+export function isMeaningfulTitle(title) {
+  if (typeof title !== 'string') return false
+  const trimmed = title.trim().toLowerCase()
+  if (!trimmed) return false
+  const placeholders = new Set([
+    '新会话', '新建会话', 'new session', 'new chat', 'untitled', '新任务', 'new task'
+  ])
+  return !placeholders.has(trimmed)
+}
+
+/** The one separator that follows a root spelling in a prefix test. */
+const SEPARATORS = new Set(['/', '\\'])
+
+/** Whether `child` is `root` itself or lies inside it (both canonical absolute paths). */
+export function sameOrInside(root, child) {
+  if (child === root) return true
+  const prefix = root !== '' && SEPARATORS.has(root.at(-1)) ? root : root + sep
+  return child.startsWith(prefix)
+}
+
+/**
+ * Whether one directory currently isolates its sessions.
+ * @param root - absolute directory path.
+ * @param defaultPath - optional default workspace path to auto-isolate.
+ * @returns true when marked or when matching the default workspace.
+ */
+export async function isIsolated(root, defaultPath) {
+  if (typeof root !== 'string' || root === '') return false
+  if (defaultPath && root === defaultPath) return true
+  try {
+    return (await stat(join(root, MARKER_NAME))).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** The comment a freshly written marker carries. */
+const MARKER_TEXT = [
+  '# DeepSeek Harness per-session working directories',
+  '#',
+  '# While this file exists, every new session created in this directory works in',
+  '# its own "session-<id>" subfolder instead of the directory itself, so',
+  '# concurrent sessions cannot overwrite each other\'s files.',
+  '#',
+  '# Delete this file to share one working directory again. Sessions already',
+  '# created keep the folder they were created in.',
+  '',
+].join('\n')
+
+/**
+ * Enable or disable isolation for one directory by writing or removing its marker.
+ * @param root - absolute directory path.
+ * @param enabled - target state.
+ * @returns the state that is now on disk.
+ */
+export async function setIsolated(root, enabled) {
+  const marker = join(root, MARKER_NAME)
+  if (!enabled) {
+    await rm(marker, { force: true })
+    return false
+  }
+  await mkdir(root, { recursive: true })
+  await writeFile(marker, MARKER_TEXT, 'utf8')
+  return true
+}
+
+/**
+ * Every marked directory that is an ancestor of `path`, nearest first.
+ * @param roots - candidate marked directories.
+ * @param path - absolute directory to test.
+ * @returns matching roots in nearest-first order.
+ */
+export function containingRoots(roots, path) {
+  return [...roots]
+    .filter(root => sameOrInside(root, path))
+    .sort((left, right) => right.length - left.length)
+}
+
+/**
+ * The nearest marked ancestor of `path`, if any.
+ * @param roots - candidate marked directories.
+ * @param path - absolute directory to test.
+ * @returns the owning marked directory, or undefined.
+ */
+export function owningRoot(roots, path) {
+  return containingRoots(roots, path)[0]
+}
+
+/**
+ * Allocate one private directory for a session under an isolating directory.
+ *
+ * The name keeps the `session-<id>` shape: the first eight characters of
+ * the session id, with `-2`, `-3`, … on collision.
+ * If a collided candidate is completely empty (abandoned draft), it is reused.
+ * @param root - isolating directory.
+ * @param sessionId - the session's id.
+ * @param isDirectoryEmptyFn - optional predicate to check if an existing folder is empty.
+ * @returns the absolute directory path, created on disk.
+ */
+export async function allocateSessionDir(root, sessionId, isDirectoryEmptyFn) {
+  const flattened = String(sessionId).replace(/^session-/, '').replaceAll('-', '')
+  const short = flattened.slice(0, 8) === '' ? 'unknown' : flattened.slice(0, 8)
+  for (let attempt = 1; ; attempt += 1) {
+    const suffix = attempt === 1 ? '' : `-${attempt}`
+    const candidate = resolve(join(root, `${SESSION_DIR_PREFIX}${short}${suffix}`))
+    try {
+      await mkdir(candidate)
+      return candidate
+    } catch (error) {
+      if (error !== null && typeof error === 'object' && error.code === 'EEXIST') {
+        if (typeof isDirectoryEmptyFn === 'function') {
+          const empty = await isDirectoryEmptyFn(candidate).catch(() => false)
+          if (empty) return candidate
+        }
+        continue
+      }
+      throw error
+    }
+  }
+}