@wangxiaocuo/dsh-session-trash 0.0.0-stage → 0.6.0

package/lib/inventory.js

@@ -0,0 +1,426 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { entryKind, isSafeDirectoryPath, isSafeMemberId, isSafeTrashId, samePath } from './fsops.js'
+
+/** Every state the durable index understands. */
+export const ENTRY_STATES = new Set(['trashing', 'trashed', 'restoring', 'purging', 'missing'])
+
+/** Sidecar schema version understood by this release. */
+const META_VERSION = 2
+
+/** Maximum directories one trashed item may own. */
+const MAX_MEMBERS = 64
+
+/**
+ * @param {unknown} value candidate timestamp.
+ * @returns {boolean} whether the value is a finite number.
+ */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * @param {unknown} value candidate metric.
+ * @returns {boolean} whether the value is a usable number or absent.
+ */
+function isMetric(value) {
+  return value === undefined || value === null || isFiniteNumber(value)
+}
+
+/**
+ * Validate one v2 member's absolute paths. The parent's sidecar is validated
+ * field by field so a hand-edited file is rejected instead of guessed at.
+ *
+ * @param {unknown} member candidate member.
+ * @returns {boolean} whether the member names safe, coherent paths.
+ */
+function isValidMemberPaths(member) {
+  if (member === null || typeof member !== 'object' || Array.isArray(member)) return false
+  if (!isSafeMemberId(member.sessionId)) return false
+  if (member.origin !== undefined && member.origin !== null && member.origin !== 'subagent') return false
+  if (member.title !== undefined && typeof member.title !== 'string') return false
+  if (
+    member.formatStatus !== undefined &&
+    member.formatStatus !== 'current' &&
+    member.formatStatus !== 'migration-required'
+  ) {
+    return false
+  }
+  if (!isMetric(member.sizeBytes) || !isMetric(member.fileCount)) return false
+  if (!isSafeDirectoryPath(member.originalSessionDir)) return false
+  if (typeof member.originalLogPath !== 'string' || !path.isAbsolute(member.originalLogPath)) return false
+  if (
+    typeof member.persistenceProjectDirHint !== 'string' ||
+    !path.isAbsolute(member.persistenceProjectDirHint)
+  ) {
+    return false
+  }
+  if (!samePath(path.dirname(path.resolve(member.originalSessionDir)), path.resolve(member.persistenceProjectDirHint))) {
+    return false
+  }
+  if (!samePath(path.dirname(path.resolve(member.originalLogPath)), path.resolve(member.originalSessionDir))) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Validate the v2 member list of one sidecar.
+ *
+ * @param {object} meta candidate sidecar.
+ * @returns {boolean} whether the list is coherent with its parent fields.
+ */
+function isValidMetaMembers(meta) {
+  if (!Array.isArray(meta.members) || meta.members.length === 0 || meta.members.length > MAX_MEMBERS) return false
+  if (!meta.members.every((member) => isValidMemberPaths(member))) return false
+  const seen = new Set()
+  for (const member of meta.members) {
+    if (seen.has(member.sessionId)) return false
+    seen.add(member.sessionId)
+  }
+  const parent = meta.members[0]
+  if (parent.sessionId !== meta.sessionId) return false
+  if (!samePath(path.resolve(parent.originalSessionDir), path.resolve(meta.originalSessionDir))) return false
+  if (!samePath(path.resolve(parent.originalLogPath), path.resolve(meta.originalLogPath))) return false
+  if (
+    !samePath(path.resolve(parent.persistenceProjectDirHint), path.resolve(meta.persistenceProjectDirHint))
+  ) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Validate one object sidecar strictly enough to be rebuilt into an index
+ * entry. A malformed sidecar is reported as an unindexed object instead of
+ * being guessed at.
+ *
+ * @param {unknown} meta parsed `meta.json`.
+ * @param {string} trashId object directory identity.
+ * @returns {boolean} whether the sidecar can rebuild one entry.
+ */
+export function isValidMeta(meta, trashId) {
+  if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return false
+  if (meta.version !== undefined && meta.version !== META_VERSION && meta.version !== 1) return false
+  if (typeof meta.sessionId !== 'string' || meta.sessionId === '' || meta.sessionId.length > 256) return false
+  if (meta.trashId !== trashId) return false
+  if (!ENTRY_STATES.has(meta.state)) return false
+  if (!isFiniteNumber(meta.trashedAt) || !isFiniteNumber(meta.startedAt)) return false
+  if (typeof meta.title !== 'string' || meta.title.trim() === '') return false
+  if (!isSafeDirectoryPath(meta.originalSessionDir)) return false
+  if (typeof meta.persistenceProjectDirHint !== 'string' || !path.isAbsolute(meta.persistenceProjectDirHint)) return false
+  if (!samePath(path.dirname(path.resolve(meta.originalSessionDir)), path.resolve(meta.persistenceProjectDirHint))) return false
+  if (typeof meta.originalLogPath !== 'string' || !path.isAbsolute(meta.originalLogPath)) return false
+  if (!samePath(path.dirname(path.resolve(meta.originalLogPath)), path.resolve(meta.originalSessionDir))) return false
+  if (meta.originalCwd !== null && meta.originalCwd !== undefined) {
+    if (typeof meta.originalCwd !== 'string' || !path.isAbsolute(meta.originalCwd)) return false
+  }
+  if (
+    meta.workspaceExistsAtDeletion !== null &&
+    meta.workspaceExistsAtDeletion !== undefined &&
+    typeof meta.workspaceExistsAtDeletion !== 'boolean'
+  ) {
+    return false
+  }
+  if (meta.version === META_VERSION) return isValidMetaMembers(meta)
+  return true
+}
+
+/**
+ * @param {Record<string, unknown>} member raw member fields.
+ * @param {string} fallbackTitle title used when the member carries none.
+ * @returns {object} one normalized v2 member.
+ */
+function toMember(member, fallbackTitle) {
+  return {
+    sessionId: member.sessionId,
+    origin: member.origin === 'subagent' ? 'subagent' : null,
+    title: typeof member.title === 'string' && member.title !== '' ? member.title : fallbackTitle,
+    originalSessionDir: path.resolve(member.originalSessionDir),
+    originalLogPath: path.resolve(member.originalLogPath),
+    persistenceProjectDirHint: path.resolve(member.persistenceProjectDirHint),
+    formatStatus: member.formatStatus === 'migration-required' ? 'migration-required' : 'current',
+    sizeBytes: isFiniteNumber(member.sizeBytes) ? member.sizeBytes : null,
+    fileCount: isFiniteNumber(member.fileCount) ? member.fileCount : null,
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} meta valid sidecar.
+ * @returns {object} a clean index entry with defaulted optional fields.
+ */
+export function toEntry(meta) {
+  const originalCwd = typeof meta.originalCwd === 'string' && meta.originalCwd !== '' ? meta.originalCwd : null
+  const title = typeof meta.title === 'string' && meta.title !== '' ? meta.title : meta.sessionId
+  const members =
+    Array.isArray(meta.members) && meta.members.length > 0
+      ? meta.members.map((member) => toMember(member, title))
+      : [
+          toMember(
+            {
+              sessionId: meta.sessionId,
+              originalSessionDir: meta.originalSessionDir,
+              originalLogPath: meta.originalLogPath,
+              persistenceProjectDirHint: meta.persistenceProjectDirHint,
+              formatStatus: meta.formatStatus,
+              sizeBytes: meta.sizeBytes,
+              fileCount: meta.fileCount,
+            },
+            title,
+          ),
+        ]
+  return {
+    sessionId: meta.sessionId,
+    trashId: meta.trashId,
+    state: meta.state,
+    title,
+    trashedAt: meta.trashedAt,
+    startedAt: meta.startedAt,
+    originalCwd,
+    workspaceExistsAtDeletion: typeof meta.workspaceExistsAtDeletion === 'boolean' ? meta.workspaceExistsAtDeletion : null,
+    originalWorkspaceId: typeof meta.originalWorkspaceId === 'string' ? meta.originalWorkspaceId : null,
+    originalWorkspaceTitle: typeof meta.originalWorkspaceTitle === 'string' ? meta.originalWorkspaceTitle : null,
+    originalNextSessionId: typeof meta.originalNextSessionId === 'string' ? meta.originalNextSessionId : null,
+    originalSessionDir: path.resolve(meta.originalSessionDir),
+    originalLogPath: path.resolve(meta.originalLogPath),
+    persistenceProjectDirHint: path.resolve(meta.persistenceProjectDirHint),
+    formatStatus: meta.formatStatus === 'migration-required' ? 'migration-required' : 'current',
+    sizeBytes: isFiniteNumber(meta.sizeBytes) ? meta.sizeBytes : null,
+    fileCount: isFiniteNumber(meta.fileCount) ? meta.fileCount : null,
+    members,
+    lastError: typeof meta.lastError === 'string' && meta.lastError !== '' ? meta.lastError : null,
+  }
+}
+
+/**
+ * Which of one entry's member directories currently exist inside its object.
+ *
+ * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
+ * @param {object} entry index entry, v1 or v2 shaped.
+ * @returns {Promise<{ total: number, present: number, missing: string[] }>} presence summary.
+ */
+export async function memberPresence(store, entry) {
+  const members =
+    Array.isArray(entry.members) && entry.members.length > 0
+      ? entry.members
+      : [{ sessionId: entry.sessionId, originalSessionDir: entry.originalSessionDir }]
+  const missing = []
+  let present = 0
+  for (let index = 0; index < members.length; index += 1) {
+    const member = members[index]
+    let kind = 'missing'
+    try {
+      kind = await entryKind(store.memberPath(entry.trashId, index, member.sessionId))
+    } catch {
+      kind = 'missing'
+    }
+    if (kind === 'directory') present += 1
+    else missing.push(typeof member.sessionId === 'string' ? member.sessionId : entry.sessionId)
+  }
+  return { total: members.length, present, missing }
+}
+
+/**
+ * Reconcile a rebuilt entry with the object directory observed on disk.
+ *
+ * @param {object} entry index-shaped entry.
+ * @param {{ total: number, present: number, missing: string[] }} presence member presence.
+ * @param {number} now current timestamp.
+ * @returns {object} the entry whose state matches the filesystem.
+ */
+export function deriveEntry(entry, presence, now) {
+  const complete = presence.total > 0 && presence.present === presence.total
+  if (!complete) {
+    if (entry.state === 'purging' || entry.state === 'missing') return { ...entry }
+    const lastError =
+      presence.present === 0
+        ? 'The trash copy of this session is missing.'
+        : `The trash copy is missing these member sessions: ${presence.missing.join(', ')}.`
+    return {
+      ...entry,
+      state: 'missing',
+      lastError,
+    }
+  }
+  if (entry.state === 'missing') {
+    return {
+      ...entry,
+      state: 'trashed',
+      trashedAt: isFiniteNumber(entry.trashedAt) && entry.trashedAt > 0 ? entry.trashedAt : entry.startedAt || now,
+      lastError: null,
+    }
+  }
+  if (entry.state === 'trashed' && (!isFiniteNumber(entry.trashedAt) || entry.trashedAt <= 0)) {
+    return { ...entry, trashedAt: entry.startedAt || now }
+  }
+  return { ...entry }
+}
+
+/**
+ * Read every object directory and its sidecar without following symlinks.
+ *
+ * @param {import('./store.js').TrashStore} store trash store owning `objects/`.
+ * @param {{ warn: Function }} logger diagnostics sink.
+ * @returns {Promise<{ objects: { trashId: string, sessionExists: boolean, meta: object | undefined, metaValid: boolean, entry?: object, presence?: object }[], unindexed: number }>} the inventory.
+ */
+export async function scanObjects(store, logger) {
+  let entries
+  try {
+    entries = await fs.readdir(store.objectsDir, { withFileTypes: true })
+  } catch (error) {
+    if (error !== null && error !== undefined && error.code === 'ENOENT') return { objects: [], unindexed: 0 }
+    throw error
+  }
+  const objects = []
+  let unindexed = 0
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !isSafeTrashId(entry.name)) {
+      unindexed += 1
+      continue
+    }
+    const trashId = entry.name
+    let meta
+    try {
+      meta = await store.readMeta(trashId)
+    } catch (error) {
+      logger.warn(`cannot read the trash metadata for ${trashId}: ${error instanceof Error ? error.message : String(error)}`)
+      // Keep the directory in the inventory so reconcile never mistakes an
+      // unreadable sidecar for a vanished object directory.
+      objects.push({ trashId, sessionExists: false, meta: undefined, metaValid: false })
+      unindexed += 1
+      continue
+    }
+    const metaValid = meta !== undefined && isValidMeta(meta, trashId)
+    if (!metaValid) {
+      objects.push({ trashId, sessionExists: false, meta, metaValid: false })
+      unindexed += 1
+      continue
+    }
+    let presence
+    try {
+      presence = await memberPresence(store, toEntry(meta))
+    } catch (error) {
+      logger.warn(`cannot inspect the trash copy ${trashId}: ${error instanceof Error ? error.message : String(error)}`)
+      presence = { total: 0, present: 0, missing: [] }
+    }
+    objects.push({
+      trashId,
+      sessionExists: presence.total > 0 && presence.present === presence.total,
+      meta,
+      metaValid,
+      entry: toEntry(meta),
+      presence,
+    })
+  }
+  return { objects, unindexed }
+}
+
+/**
+ * Import object directories the index does not know about and mark entries
+ * whose object directory vanished. Never deletes a session file or an object
+ * directory.
+ *
+ * @param {{ store: import('./store.js').TrashStore, logger: { warn: Function }, now?: number }} input trash store and diagnostics.
+ * @returns {Promise<{ imported: number, markedMissing: number, unindexed: number, changed: number }>} reconcile summary.
+ */
+export async function reconcileIndex({ store, logger, now = Date.now() }) {
+  if (store.isProtected()) return { imported: 0, markedMissing: 0, unindexed: store.unindexed, changed: 0 }
+  const { objects, unindexed: invalidObjects } = await scanObjects(store, logger)
+  const byTrashId = new Map(objects.map((object) => [object.trashId, object]))
+  const nextEntries = [...store.entries()]
+  const indexedTrashIds = new Set(nextEntries.map((entry) => entry.trashId))
+  const sessionIds = new Set(nextEntries.map((entry) => entry.sessionId))
+  const metaUpdates = []
+  let unindexed = invalidObjects
+  let markedMissing = 0
+  let imported = 0
+  let changed = false
+
+  for (let index = 0; index < nextEntries.length; index += 1) {
+    const entry = nextEntries[index]
+    const object = byTrashId.get(entry.trashId)
+    if (object === undefined) {
+      if (entry.state !== 'trashed') continue
+      nextEntries[index] = {
+        ...entry,
+        state: 'missing',
+        lastError: entry.lastError ?? 'The trash object directory is missing.',
+      }
+      metaUpdates.push(nextEntries[index])
+      markedMissing += 1
+      changed = true
+      continue
+    }
+    const presence = await memberPresence(store, entry)
+    if (entry.state === 'missing' && presence.total > 0 && presence.present === presence.total) {
+      nextEntries[index] = {
+        ...entry,
+        state: 'trashed',
+        trashedAt: entry.trashedAt > 0 ? entry.trashedAt : entry.startedAt || now,
+        lastError: null,
+      }
+      metaUpdates.push(nextEntries[index])
+      changed = true
+    }
+  }
+
+  for (const object of objects) {
+    if (indexedTrashIds.has(object.trashId)) continue
+    if (!object.metaValid || object.meta === undefined || object.entry === undefined || object.presence === undefined) continue
+    const entry = object.entry
+    if (sessionIds.has(entry.sessionId)) {
+      // Two object directories claim the same session: keep the indexed one.
+      unindexed += 1
+      logger.warn(`the trash object ${object.trashId} duplicates the indexed session ${entry.sessionId}`)
+      continue
+    }
+    const derived = deriveEntry(entry, object.presence, now)
+    nextEntries.push(derived)
+    indexedTrashIds.add(derived.trashId)
+    sessionIds.add(derived.sessionId)
+    metaUpdates.push(derived)
+    imported += 1
+    changed = true
+  }
+
+  if (changed) {
+    await store.commit(nextEntries)
+    for (const entry of metaUpdates) {
+      await store.writeMeta(entry).catch((error) => {
+        logger.warn(`cannot rewrite trash metadata for ${entry.trashId}: ${error instanceof Error ? error.message : String(error)}`)
+      })
+    }
+  }
+  store.unindexed = unindexed
+  return { imported, markedMissing, unindexed, changed: changed ? 1 : 0 }
+}
+
+/**
+ * Rebuild the complete index from one `meta.json` sidecar per object directory.
+ * Used only after the primary index and its backup were both rejected;
+ * unindexed directories stay untouched and are reported.
+ *
+ * @param {{ store: import('./store.js').TrashStore, logger: { warn: Function }, now?: number }} input trash store and diagnostics.
+ * @returns {Promise<{ entries: number, unindexed: number }>} rebuild summary.
+ */
+export async function rebuildIndex({ store, logger, now = Date.now() }) {
+  const { objects, unindexed: invalidObjects } = await scanObjects(store, logger)
+  const entries = []
+  const seen = new Set()
+  let unindexed = invalidObjects
+  for (const object of objects) {
+    if (!object.metaValid || object.meta === undefined || object.entry === undefined || object.presence === undefined) continue
+    const entry = object.entry
+    if (seen.has(entry.sessionId)) {
+      unindexed += 1
+      logger.warn(`the trash object ${object.trashId} duplicates the rebuilt session ${entry.sessionId}`)
+      continue
+    }
+    seen.add(entry.sessionId)
+    entries.push(deriveEntry(entry, object.presence, now))
+  }
+  entries.sort((left, right) => left.startedAt - right.startedAt || left.trashId.localeCompare(right.trashId))
+  await store.commit(entries)
+  store.unindexed = unindexed
+  return { entries: entries.length, unindexed }
+}

package/lib/members.js

@@ -0,0 +1,95 @@
+/**
+ * One trashed item may own several session directories: the visible parent and
+ * every hidden `origin: 'subagent'` descendant. These helpers keep the v1
+ * single-directory shape readable while the durable index uses the v2
+ * `members` array.
+ *
+ * @module dsh-session-trash/members
+ */
+
+/**
+ * @param {unknown} entry index entry (v1 or v2 shape).
+ * @returns {object|null} the parent member, or null when the entry has no directory data.
+ */
+export function parentMember(entry) {
+  if (entry === null || typeof entry !== 'object') return null
+  if (typeof entry.sessionId !== 'string' || entry.sessionId === '') return null
+  return {
+    sessionId: entry.sessionId,
+    origin: null,
+    title: typeof entry.title === 'string' ? entry.title : entry.sessionId,
+    originalSessionDir: entry.originalSessionDir,
+    originalLogPath: entry.originalLogPath,
+    persistenceProjectDirHint: entry.persistenceProjectDirHint,
+    formatStatus: entry.formatStatus,
+    sizeBytes: entry.sizeBytes,
+    fileCount: entry.fileCount,
+  }
+}
+
+/**
+ * @param {unknown} entry index entry (v1 or v2 shape).
+ * @returns {object[]} every owned directory, parent first.
+ */
+export function memberList(entry) {
+  if (entry !== null && typeof entry === 'object' && Array.isArray(entry.members) && entry.members.length > 0) {
+    return entry.members
+  }
+  const parent = parentMember(entry)
+  return parent === null ? [] : [parent]
+}
+
+/**
+ * @param {readonly object[]} members member list.
+ * @returns {{ sizeBytes: number, fileCount: number }} summed measurable totals.
+ */
+export function aggregateMetrics(members) {
+  let sizeBytes = 0
+  let fileCount = 0
+  for (const member of members) {
+    if (typeof member?.sizeBytes === 'number') sizeBytes += member.sizeBytes
+    if (typeof member?.fileCount === 'number') fileCount += member.fileCount
+  }
+  return { sizeBytes, fileCount }
+}
+
+/**
+ * Shape-level validation shared by the durable index and object sidecars.
+ * Path strictness belongs to the sidecar validator.
+ *
+ * @param {unknown} member candidate member.
+ * @returns {boolean} whether the member carries the required v2 identity.
+ */
+export function isValidMemberShape(member) {
+  if (member === null || typeof member !== 'object' || Array.isArray(member)) return false
+  if (typeof member.sessionId !== 'string' || member.sessionId === '' || member.sessionId.length > 256) return false
+  if (member.origin !== undefined && member.origin !== null && member.origin !== 'subagent') return false
+  if (member.title !== undefined && typeof member.title !== 'string') return false
+  if (member.formatStatus !== undefined && member.formatStatus !== 'current' && member.formatStatus !== 'migration-required') {
+    return false
+  }
+  if (member.sizeBytes !== undefined && member.sizeBytes !== null && typeof member.sizeBytes !== 'number') return false
+  if (member.fileCount !== undefined && member.fileCount !== null && typeof member.fileCount !== 'number') return false
+  for (const key of ['originalSessionDir', 'originalLogPath', 'persistenceProjectDirHint']) {
+    if (member[key] !== undefined && member[key] !== null && typeof member[key] !== 'string') return false
+  }
+  return true
+}
+
+/**
+ * Whether the v2 member list is internally consistent with its parent entry.
+ *
+ * @param {unknown} entry index entry carrying `members`.
+ * @returns {boolean} whether the list is acceptable.
+ */
+export function isValidMemberList(entry) {
+  if (entry === null || typeof entry !== 'object') return false
+  if (!Array.isArray(entry.members) || entry.members.length === 0 || entry.members.length > 64) return false
+  const seen = new Set()
+  for (const member of entry.members) {
+    if (!isValidMemberShape(member)) return false
+    if (seen.has(member.sessionId)) return false
+    seen.add(member.sessionId)
+  }
+  return entry.members[0].sessionId === entry.sessionId
+}

package/lib/paths.js

@@ -0,0 +1,39 @@
+import path from 'node:path'
+import { resolveDshHome, dshHomePath, dshHomeDisplay } from '@deepseek-ai/dsh-home-paths'
+import { TrashError } from './errors.js'
+
+/** Trash directory name under the DSH home. */
+export const TRASH_DIRNAME = '.session-trash'
+
+/**
+ * Resolve every trash path from the harness home.
+ *
+ * The host refuses to activate when the shared path library cannot produce an
+ * absolute home, so no caller falls back to an environment guess of its own.
+ *
+ * @returns {{ home: string, root: string, display: string }} resolved absolute paths plus the symbolic display form.
+ */
+export function resolveTrashPaths() {
+  let home
+  try {
+    home = resolveDshHome()
+  } catch (cause) {
+    throw new TrashError(
+      'HOME_UNRESOLVED',
+      `Cannot resolve the DeepSeek Harness home: ${cause instanceof Error ? cause.message : String(cause)}`,
+    )
+  }
+  if (typeof home !== 'string' || home === '' || !path.isAbsolute(home)) {
+    throw new TrashError(
+      'HOME_UNRESOLVED',
+      '@deepseek-ai/dsh-home-paths resolved a non-absolute harness home; the trash plugin refuses to activate.',
+    )
+  }
+  const root = dshHomePath(TRASH_DIRNAME)
+  if (typeof root !== 'string' || !path.isAbsolute(root)) {
+    throw new TrashError('HOME_UNRESOLVED', '@deepseek-ai/dsh-home-paths did not produce an absolute trash root.')
+  }
+  const homeLabel = dshHomeDisplay(home)
+  const display = `${homeLabel === undefined || homeLabel === null || homeLabel === '' ? home : homeLabel}/${TRASH_DIRNAME}`
+  return { home, root, display }
+}