@anionex/dsh-turn-rewind 0.2.2 → 0.3.0

package/lib/types/workspace.d.ts

@@ -0,0 +1,37 @@
+import { type DirectorySnapshotSource } from './directory.js';
+import { type RepositorySnapshotSource } from './git.js';
+import type { ResolvedChangeLedgerConfig, WorkspaceState } from './types.js';
+/** Eligible snapshot source for either supported workspace mode. */
+export type WorkspaceSnapshotSource = RepositorySnapshotSource | DirectorySnapshotSource;
+/**
+ * Discover the owning Git worktree, or treat `cwd` itself as an ordinary
+ * directory when it is not inside any repository.
+ * @param cwd - working directory the Session runs in.
+ * @param config - capture limits applied to ordinary-directory enumeration.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source for the owning workspace.
+ */
+export declare function discoverWorkspace(cwd: string, config: Pick<ResolvedChangeLedgerConfig, 'maxFiles' | 'maxFileBytes'>, signal?: AbortSignal): Promise<WorkspaceSnapshotSource>;
+/** Workspace mode and root resolved without inventorying any files. */
+export interface WorkspaceIdentity {
+    readonly type: WorkspaceState['type'];
+    readonly root: string;
+}
+/**
+ * Resolve the workspace mode and root without inventorying files, for callers
+ * that only need to address the workspace (locks, skip markers, storage purge).
+ * @param cwd - working directory the Session runs in.
+ * @param signal - optional caller cancellation.
+ * @returns the workspace mode and canonical root.
+ */
+export declare function discoverWorkspaceIdentity(cwd: string, signal?: AbortSignal): Promise<WorkspaceIdentity>;
+/** Resolve the workspace root without inventorying its files. */
+export declare function discoverWorkspaceRoot(cwd: string, signal?: AbortSignal): Promise<string>;
+/**
+ * Whether two fences still describe the same workspace.
+ *
+ * Git workspaces keep the full repository fence (HEAD, branch, operation);
+ * ordinary directories only own their canonical root, so a moved or recreated
+ * root is the only thing that can invalidate them.
+ */
+export declare function sameWorkspaceFence(left: WorkspaceState, right: WorkspaceState): boolean;

package/lib/validate.js

@@ -99,7 +99,9 @@ export function parseManifest(value) {
         return { version, ...common };
     if (restorePointKind !== 'turn')
         corrupt('Git-native v2 restore points are automatic turn checkpoints');
-    return { version, ...common, git: parseGitCheckpoint(record.git, id) };
+    if (repository.type !== 'git')
+        corrupt('Git-native v2 restore points must fence a Git workspace');
+    return { version, ...common, repository, git: parseGitCheckpoint(record.git, id) };
 }
 /** Parse an untrusted durable restore-operation journal. */
 export function parseOperation(value) {
@@ -155,9 +157,28 @@ export function validateBlobHash(value) {
     }
     return value;
 }
+/**
+ * Parse the durable workspace fence of one manifest.
+ *
+ * A missing `type` is the only legacy interpretation: manifests written before
+ * ordinary-directory support are always Git workspaces and are upgraded in
+ * memory. Directory fences must not carry Git-only fields.
+ * @param value - persisted `repository` field.
+ * @returns the validated workspace state.
+ */
 function parseRepository(value) {
     const record = objectRecord(value, 'repository state');
     const root = absoluteString(record, 'root');
+    if (record.type === 'directory') {
+        for (const key of ['commonDir', 'head', 'branch', 'operation', 'stagedPaths']) {
+            if (record[key] !== undefined)
+                corrupt(`directory workspace state must not contain ${key}`);
+        }
+        return { type: 'directory', root };
+    }
+    if (record.type !== undefined && record.type !== 'git') {
+        corrupt('workspace state type must be "git" or "directory"');
+    }
     const commonDir = absoluteString(record, 'commonDir');
     const head = optionalHash(record, 'head');
     const branch = optionalString(record, 'branch');
@@ -167,6 +188,7 @@ function parseRepository(value) {
         corrupt('repository stagedPaths must be an array');
     const stagedPaths = stagedValue.map((path) => validateRelativePath(requireString(path, 'staged path')));
     return {
+        type: 'git',
         root,
         commonDir,
         ...(head === undefined ? {} : { head }),

package/lib/workspace.js

@@ -0,0 +1,45 @@
+import { discoverDirectory, discoverDirectoryRoot } from './directory.js';
+import { discoverRepositoryOptional, discoverRepositoryRootOptional, sameRepositoryFence, } from './git.js';
+/**
+ * Discover the owning Git worktree, or treat `cwd` itself as an ordinary
+ * directory when it is not inside any repository.
+ * @param cwd - working directory the Session runs in.
+ * @param config - capture limits applied to ordinary-directory enumeration.
+ * @param signal - optional caller cancellation.
+ * @returns the snapshot source for the owning workspace.
+ */
+export async function discoverWorkspace(cwd, config, signal) {
+    const repository = await discoverRepositoryOptional(cwd, signal);
+    return repository ?? discoverDirectory(cwd, config, signal);
+}
+/**
+ * Resolve the workspace mode and root without inventorying files, for callers
+ * that only need to address the workspace (locks, skip markers, storage purge).
+ * @param cwd - working directory the Session runs in.
+ * @param signal - optional caller cancellation.
+ * @returns the workspace mode and canonical root.
+ */
+export async function discoverWorkspaceIdentity(cwd, signal) {
+    const root = await discoverRepositoryRootOptional(cwd, signal);
+    return root === undefined
+        ? { type: 'directory', root: await discoverDirectoryRoot(cwd) }
+        : { type: 'git', root };
+}
+/** Resolve the workspace root without inventorying its files. */
+export async function discoverWorkspaceRoot(cwd, signal) {
+    return (await discoverWorkspaceIdentity(cwd, signal)).root;
+}
+/**
+ * Whether two fences still describe the same workspace.
+ *
+ * Git workspaces keep the full repository fence (HEAD, branch, operation);
+ * ordinary directories only own their canonical root, so a moved or recreated
+ * root is the only thing that can invalidate them.
+ */
+export function sameWorkspaceFence(left, right) {
+    if (left.type !== right.type || left.root !== right.root)
+        return false;
+    if (left.type === 'directory' || right.type === 'directory')
+        return true;
+    return sameRepositoryFence(left, right);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-turn-rewind",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Turn-level conversation and workspace rewind for DeepSeek Harness, powered by a persistent Change Ledger",
   "repository": {
     "type": "git",
@@ -109,5 +109,8 @@
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
-  "packageManager": "pnpm@11.7.0"
+  "packageManager": "pnpm@11.7.0",
+  "dependencies": {
+    "ignore": "^7.0.9"
+  }
 }

package/src/client/index.tsx

@@ -1214,9 +1214,12 @@ function friendlyError(error: unknown): string {
     case 'REWIND_ENDPOINT_UNAVAILABLE': return '回退服务没有响应。请确认 @anionex/dsh-turn-rewind 已挂载到当前 DSH，并重启 DSH 后重试。'
     case 'REWIND_INVALID_RESPONSE': return '回退服务返回了无法解析的内容。请重启 DSH 后重试。'
     case 'PLAN_STALE': return '项目文件在检查后又发生了变化。为避免覆盖新修改，请重新检查后再恢复。'
+    case 'PLAN_STALE_WORKSPACE': return '项目文件在检查后又发生了变化。为避免覆盖新修改，请重新检查后再恢复。'
     case 'PLAN_STALE_REPOSITORY': return 'Git 状态在检查后又发生了变化，恢复已失效。请重新检查后再试。'
     case 'WORKSPACE_IN_USE': return '这个项目目录还有别的对话正在运行。请等那些对话结束或停止后，再重新检查。'
     case 'WORKSPACE_LOCKED': return '另一个恢复操作正在处理这个项目目录。请等待它完成后重新检查。'
+    case 'WORKSPACE_CHANGED': return '这个项目目录已经不在原来的位置，旧的回退点无法再使用。'
+    case 'WORKSPACE_MODE_CHANGED': return '这个项目目录的工作区类型变了（例如从普通目录变成了 Git 仓库）。旧的回退点不再适用，请重新发送一条消息生成新的回退点。'
     case 'HEAD_CHANGED': return '项目的提交或分支已发生变化。为避免覆盖新改动，请重新检查后再恢复。'
     case 'REPOSITORY_CHANGED': return '这个项目目录已不属于原来的 Git 工作区，无法恢复。'
     case 'GIT_OPERATION_CHANGED': return 'Git 正在执行其他操作。请先完成或取消该操作，再重新检查。'
@@ -1248,6 +1251,10 @@ export function explainCheckpointFailure(message: string): string {
     case 'SNAPSHOT_TOO_LARGE':
     case 'TOO_MANY_FILES':
       return '本轮有文件超过检查点的大小或数量上限，没有保存文件检查点。仍可只回溯消息。'
+    case 'UNSUPPORTED_FILE_TYPE':
+      return '项目目录里有无法保存的特殊文件（如 socket、设备文件、FIFO），没有保存文件检查点。仍可只回溯消息。'
+    case 'IGNORE_FILE_INVALID':
+      return '项目目录里的 .dsh-rewindignore 内容无效，没有保存文件检查点。修正该文件后可重新发送消息。'
     case 'INVALID_PATH':
       return '项目目录里有无法安全保存的路径（例如嵌套的独立 Git 仓库），没有保存文件检查点。仍可只回溯消息。'
     default:

package/src/directory.ts

@@ -0,0 +1,194 @@
+import type { BigIntStats } from 'node:fs'
+import { lstat, readFile, readdir, realpath } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import ignore, { type Ignore } from 'ignore'
+import { ChangeLedgerError } from './errors.js'
+import { canonicalDirectory, isNodeError, isWithin } from './path-utils.js'
+import type { DirectoryWorkspaceState, ResolvedChangeLedgerConfig } from './types.js'
+
+const IGNORE_FILE = '.dsh-rewindignore'
+const DEFAULT_IGNORE_PATTERNS = ['.git', 'node_modules'] as const
+
+/** Ordinary-directory discovery result plus its eligible path inventory. */
+export interface DirectorySnapshotSource {
+  readonly state: DirectoryWorkspaceState
+  readonly paths: readonly string[]
+}
+
+/** Resolve the canonical ordinary directory used as a non-Git workspace root. */
+export async function discoverDirectoryRoot(cwd: string): Promise<string> {
+  return canonicalDirectory(cwd)
+}
+
+/** Enumerate regular files and symlinks in an ordinary directory using rewind ignore rules. */
+export async function discoverDirectory(
+  cwd: string,
+  config: Pick<ResolvedChangeLedgerConfig, 'maxFiles' | 'maxFileBytes'>,
+  signal?: AbortSignal,
+): Promise<DirectorySnapshotSource> {
+  const root = await discoverDirectoryRoot(cwd)
+  const matcher = await loadIgnoreMatcher(root, config.maxFileBytes, signal)
+  const paths: string[] = []
+  await walkDirectory(root, root, '', matcher, paths, config.maxFiles, signal)
+  paths.sort(comparePaths)
+  return { state: { type: 'directory', root }, paths }
+}
+
+/**
+ * Read `.dsh-rewindignore` when present and combine it with the built-in
+ * exclusions. The built-in patterns are added last so user negation rules can
+ * never re-include the plugin's own metadata or dependency trees.
+ */
+async function loadIgnoreMatcher(root: string, maxFileBytes: number, signal?: AbortSignal): Promise<Ignore> {
+  const matcher = ignore()
+  const ignorePath = join(root, IGNORE_FILE)
+  throwIfAborted(signal)
+  let before: BigIntStats
+  try {
+    before = await lstat(ignorePath, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      matcher.add(DEFAULT_IGNORE_PATTERNS)
+      return matcher
+    }
+    throw error
+  }
+  if (!before.isFile()) {
+    throw new ChangeLedgerError('IGNORE_FILE_INVALID', `${IGNORE_FILE} must be a regular file when present`)
+  }
+  if (before.size > BigInt(maxFileBytes)) {
+    throw new ChangeLedgerError(
+      'FILE_TOO_LARGE',
+      `${JSON.stringify(IGNORE_FILE)} is ${before.size.toString()} bytes; configured per-file maximum is ${maxFileBytes}`,
+    )
+  }
+  const content = await readFile(ignorePath, 'utf8')
+  let after: BigIntStats
+  try {
+    after = await lstat(ignorePath, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `${IGNORE_FILE} disappeared while its rules were being read`)
+    }
+    throw error
+  }
+  if (!sameStat(before, after)) {
+    throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `${IGNORE_FILE} changed while its rules were being read`)
+  }
+  try {
+    matcher.add(content)
+  } catch (error) {
+    throw new ChangeLedgerError('IGNORE_FILE_INVALID', `${IGNORE_FILE} contains invalid ignore rules`, { cause: error })
+  }
+  matcher.add(DEFAULT_IGNORE_PATTERNS)
+  return matcher
+}
+
+/** Walk one ordinary directory without following symlinks, rejecting unstable trees. */
+async function walkDirectory(
+  root: string,
+  directory: string,
+  directoryPath: string,
+  matcher: Ignore,
+  paths: string[],
+  maxFiles: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  throwIfAborted(signal)
+  const before = await lstat(directory, { bigint: true })
+  await assertSafeDirectory(root, directory, before)
+  const entries = await readdir(directory, { withFileTypes: true })
+  const after = await lstat(directory, { bigint: true })
+  if (!sameStat(before, after)) {
+    throw new ChangeLedgerError(
+      'WORKSPACE_CHANGED_DURING_CAPTURE',
+      `directory changed while being enumerated: ${JSON.stringify(directoryPath || '.')}`,
+    )
+  }
+
+  entries.sort((left, right) => comparePaths(left.name, right.name))
+  for (const entry of entries) {
+    throwIfAborted(signal)
+    await assertSafeDirectory(root, directory, after)
+    const path = directoryPath === '' ? entry.name : `${directoryPath}/${entry.name}`
+    const target = join(directory, entry.name)
+    let info: BigIntStats
+    try {
+      info = await lstat(target, { bigint: true })
+    } catch (error) {
+      if (isNodeError(error, 'ENOENT')) continue
+      throw error
+    }
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+      if (matcher.ignores(`${path}/`)) continue
+      await walkDirectory(root, target, path, matcher, paths, maxFiles, signal)
+      continue
+    }
+    if (path !== IGNORE_FILE && matcher.ignores(path)) continue
+    if (!info.isFile() && !info.isSymbolicLink()) {
+      throw new ChangeLedgerError(
+        'UNSUPPORTED_FILE_TYPE',
+        `ordinary-directory path is not a regular file or symlink: ${JSON.stringify(path)}`,
+      )
+    }
+    paths.push(path)
+    if (paths.length > maxFiles) {
+      throw new ChangeLedgerError(
+        'TOO_MANY_FILES',
+        `workspace has more than ${maxFiles} eligible paths; latest path is ${JSON.stringify(path)}`,
+      )
+    }
+  }
+}
+
+/**
+ * Re-prove that one traversed directory is still the same real directory inside
+ * the workspace root, so a swapped symlink or moved ancestor cannot redirect
+ * the inventory outside it.
+ */
+async function assertSafeDirectory(root: string, directory: string, expected: BigIntStats): Promise<void> {
+  if (!expected.isDirectory() || expected.isSymbolicLink()) {
+    throw new ChangeLedgerError('SYMLINK_PARENT', `directory traversal reached a symbolic link: ${JSON.stringify(directory)}`)
+  }
+  let canonical: string
+  try {
+    canonical = await realpath(directory)
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT') || isNodeError(error, 'ELOOP')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory changed during traversal: ${JSON.stringify(directory)}`)
+    }
+    throw error
+  }
+  if (canonical !== resolve(directory) || !isWithin(root, canonical)) {
+    throw new ChangeLedgerError('UNSAFE_TARGET', `directory traversal escaped the workspace: ${JSON.stringify(directory)}`)
+  }
+  let current: BigIntStats
+  try {
+    current = await lstat(directory, { bigint: true })
+  } catch (error) {
+    if (isNodeError(error, 'ENOENT')) {
+      throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory disappeared during traversal: ${JSON.stringify(directory)}`)
+    }
+    throw error
+  }
+  if (!sameStat(expected, current)) {
+    throw new ChangeLedgerError('WORKSPACE_CHANGED_DURING_CAPTURE', `directory changed during traversal: ${JSON.stringify(directory)}`)
+  }
+}
+
+function sameStat(left: BigIntStats, right: BigIntStats): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeNs === right.mtimeNs
+    && left.ctimeNs === right.ctimeNs
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw signal.reason
+}
+
+function comparePaths(left: string, right: string): number {
+  return Buffer.from(left).compare(Buffer.from(right))
+}