@deepseek-ai/dsh-fs-local 0.1.5-rc.2 → 0.1.6-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/fs/fs-local/README.md
-README.md: 427cf02631f9d56246851f7fc67c92dd662c2a62
-README.zh.md: 7009d9dd853b5443780978036792f10ebc9706b5
+README.md: e781abd2032868a3768a41eb01ce5aac52f8c835
+README.zh.md: bf21f92a48c7c9d804908ee8bc25b2be8daa8967

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-fs-local` to read, list, atomically write, and edit files on the host filesystem. Relative paths resolve from a configurable base directory, while absolute paths and parent traversal remain unrestricted. Paths and symlinks that reach the same file share one identity. Writes preserve file permissions, and optional version guards reject stale overwrites. Choose this package for direct host access; use `fs-sandbox` for confined mutations or `fs-e2b` for files in a remote execution world.
+Use `dsh-fs-local` to read, list, atomically write, and edit files on the host filesystem. Relative paths resolve from a configurable base directory, while absolute paths and parent traversal remain unrestricted. Paths and symlinks that reach the same file share one identity. Writes preserve file permissions, and optional version guards reject stale overwrites. Choose this package for direct host access; use `fs-sandbox` for confined mutations.
 
 ## Table of Contents
 
@@ -29,11 +29,11 @@ Mount this backend when a composition needs `ctx.fs` backed by the real host fil
 
 ### When to choose it
 
-Choose `fs-local` for ordinary host-file access in a single process. Choose [`fs-sandbox`](../fs-sandbox/README.md) when a session's writes and edits must be confined to its workspace and temp roots — it extends this backend and adds only the mode fence. Choose [`fs-e2b`](../../e2b/fs-e2b/README.md) when files must live in a remote execution world shared with subprocesses. `config.cwd` is a resolution default, not a containment boundary: absolute paths and `..` escape it.
+Choose `fs-local` for ordinary host-file access in a single process. Choose [`fs-sandbox`](../fs-sandbox/README.md) when a session's writes and edits must be confined to its workspace and temp roots — it extends this backend and adds only the mode fence. `config.cwd` is a resolution default, not a containment boundary: absolute paths and `..` escape it.
 
 ### Minimal configuration
 
-Load the backend with a base directory; relative paths resolve against it, and absolute paths ignore it.
+Load the backend with a base directory; relative paths resolve against it, and absolute paths ignore it. A relative base is anchored to the provider process working directory, and display paths remain absolute. On POSIX, resolution follows filesystem semantics before lexical normalization: `symlink/..` reaches the parent of the link target, including when the final file does not exist yet. Directory listings preserve the same physical traversal in displayed child paths. Windows retains native drive-relative normalization.
 
 ```yaml
 - name: '@deepseek-ai/dsh-fs-local'
@@ -50,9 +50,9 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
 
 ### What you can do
 
-Read any regular UTF-8 text file whole or as a stream, read raw bytes up to a cap you choose or as one byte window, and list one directory level in stable name order. Create or replace a file atomically, and apply a literal text edit atomically; both mutations serialize per file, so concurrent writers never interleave. The version guard is optional: omit it for unconditional create-or-overwrite, or supply it to fail when the file changed since you last observed it.
+Read any regular UTF-8 text file whole or as a stream, read raw bytes up to a cap you choose or in a byte window, and list one directory level in stable name order. Create or replace a file atomically, and apply a literal text edit atomically; both mutations serialize per file, so concurrent writers never interleave. The version guard is optional: omit it for unconditional create-or-overwrite, or supply it to fail when the file changed since you last observed it.
 
-Failures are typed `FsError`s with stable codes — `FS_NOT_FOUND`, `FS_NOT_TEXT` (binary content), `FS_STALE_VERSION` (changed since observation), `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` (no unique literal match), and others — so callers branch on the code, never on message text. A missing target on a guarded edit reports `FS_STALE_VERSION` either way.
+Failures are typed `FsError`s with stable codes — `FS_NOT_FOUND`, `FS_NOT_TEXT` (binary content), `FS_STALE_VERSION` (changed since observation), `FS_EDIT_NOT_FOUND` or `FS_AMBIGUOUS_EDIT` (no unique literal match), and others — so callers branch on the code, never on message text. A missing target on an edit reports `FS_STALE_VERSION` whether or not the version guard is supplied.
 
 -----
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `dsh-fs-local` 可在宿主文件系统上读取、列出、原子写入和编辑文件。相对路径从可配置的基准目录解析，而绝对路径和父目录遍历不受限制。到达同一文件的路径和符号链接共享一个身份。写入保留文件权限，可选版本防护会拒绝陈旧覆盖。直接访问宿主文件时选择本包；需要约束变更时使用 `fs-sandbox`，文件位于远程执行世界时使用 `fs-e2b`。
+使用 `dsh-fs-local` 可在宿主文件系统上读取、列出、原子写入和编辑文件。相对路径从可配置的基准目录解析，而绝对路径和父目录遍历不受限制。到达同一文件的路径和符号链接共享一个身份。写入保留文件权限，可选版本防护会拒绝陈旧覆盖。直接访问宿主文件时选择本包；需要约束变更时使用 `fs-sandbox`。
 
 ## 目录
 
@@ -29,11 +29,11 @@ kind: "package-reference"
 
 ### 何时选择
 
-普通宿主文件访问请选择 `fs-local`。会话的写入与编辑必须限制在工作区与临时根目录内时，选择 [`fs-sandbox`](../fs-sandbox/README.zh.md)——它扩展此后端，只增加模式围栏。文件必须位于与子进程共享的远程执行世界时，选择 [`fs-e2b`](../../e2b/fs-e2b/README.zh.md)。`config.cwd` 只是解析默认值，不是约束边界：绝对路径与 `..` 都可以逃逸它。
+在单个进程中进行普通宿主文件访问时，请选择 `fs-local`。会话的写入与编辑必须限制在工作区与临时根目录内时，选择 [`fs-sandbox`](../fs-sandbox/README.zh.md)——它扩展此后端，只增加模式围栏。`config.cwd` 只是解析默认值，不是约束边界：绝对路径与 `..` 都可以逃逸它。
 
 ### 最小配置
 
-加载后端并给出基准目录；相对路径以它为基准解析，绝对路径忽略它。
+用一个基础目录加载后端；相对路径基于它解析，绝对路径则忽略它。相对基础目录以提供方进程工作目录为起点，展示路径始终保持绝对路径。在 POSIX 上，解析先遵循文件系统语义，再进行词法规范化：`symlink/..` 到达链接目标的父目录，即使最终文件尚不存在也如此。目录列表中的子项展示路径保留同样的物理遍历语义。Windows 保留原生的驱动器相对路径规范化行为。
 
 ```yaml
 - name: '@deepseek-ai/dsh-fs-local'
@@ -46,13 +46,13 @@ kind: "package-reference"
 | `cwd` | `process.cwd()` | 相对路径的基准目录 |
 | `diffBasisMaxBytes` | `10 MiB` | 每次覆写 diff 一侧的 UTF-8 字节上限；更大的覆写返回 `before: null` |
 
-生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-fs-local)是每个受支持字段及其 JSDoc 的穷尽式真源。
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-fs-local)完整列出了所有受支持字段及其 JSDoc。
 
 ### 你能做什么
 
 完整或流式读取任意普通 UTF-8 文本文件，按你选择的上限或按字节窗口读取原始字节，并按稳定名称顺序列出一层目录。原子地创建或替换文件，并原子地应用字面量文本编辑；两个变更操作都按文件串行化，并发写入方绝不会交错。版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。
 
-失败是携带稳定错误码的类型化 `FsError`——`FS_NOT_FOUND`、`FS_NOT_TEXT`（二进制内容）、`FS_STALE_VERSION`（自观察以来已变化）、`FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`（无唯一字面量匹配）等——因此调用方依据错误码分支，绝不解析消息文本。带防护的编辑遇到缺失目标时，无论哪种情况都报告 `FS_STALE_VERSION`。
+失败是携带稳定错误码的类型化 `FsError`——`FS_NOT_FOUND`、`FS_NOT_TEXT`（二进制内容）、`FS_STALE_VERSION`（自观察以来已变化）、`FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`（无唯一字面量匹配）等——因此调用方依据错误码分支，绝不解析消息文本。编辑遇到缺失目标时，无论是否提供版本防护，都报告 `FS_STALE_VERSION`。
 
 -----
 
@@ -69,8 +69,8 @@ kind: "package-reference"
 后端建立在三个想法之上：
 
 - **Realpath 身份。** `targetKey` 是文件的 `realpath`，因此经符号链接到达同一文件的两个输入路径共享一个身份，写入落在链接目标上，同时保留链接。
-- **原子发布。** 写入先写入目标旁私有暂存目录内的独占临时文件，执行 fsync 后发布；现有文件的 mode 会保留，Windows 上的 DACL 也会在替换后存活。
-- **单一变更临界区。** 每目标 FIFO 锁串行化读取→防护→写入窗口，并发写入与编辑因此被确定性排序——一方胜出，其余看到新版本并以陈旧拒绝。
+- **原子发布。** 写入先写入目标旁私有暂存目录内的独占临时文件，执行 fsync 后发布；现有文件的 mode 会保留，Windows 上的 DACL 在替换后也会保留。
+- **单一变更临界区。** 每目标 FIFO 锁串行化读取→防护→写入窗口，并发写入与编辑因此被确定性排序——一方胜出，其余操作看到新版本后因版本陈旧而被拒绝。
 
 ### 源码地图
 

package/lib/index.js

@@ -4,9 +4,9 @@ import { pathToFileURL } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { FileSystem, FsError, FsTargetKey, FsVersion } from "@deepseek-ai/dsh-fs";
 import { randomUUID } from "node:crypto";
-import { createReadStream } from "node:fs";
-import { chmod, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
-import { TextDecoder } from "node:util";
+import { createReadStream, realpath } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { TextDecoder, promisify } from "node:util";
 //#region lib/types/win32.js
 /**
 * Windows security-descriptor helpers for atomic local-file replacement. Koffi loads lazily so
@@ -93,6 +93,7 @@ async function replaceFileWin32(replaced, replacement) {
 * @module @deepseek-ai/dsh-fs-local/fsio
 */
 const BINARY_SAMPLE_BYTES = 8192;
+const realpath$1 = promisify(realpath.native);
 const DIFF_BASIS_READ_CHUNK_BYTES = 64 * 1024;
 function isENOENT(error) {
 	return error instanceof Error && "code" in error && error.code === "ENOENT";
@@ -143,6 +144,19 @@ function versionOf(info) {
 	return FsVersion(`${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`);
 }
 /**
+* Anchor a path using native drive semantics and POSIX physical parent traversal.
+* @param cwd - provider base directory for relative paths.
+* @param path - non-empty requested path.
+* @returns absolute display spelling shared by target resolution and no-follow metadata.
+*/
+function localDisplayPath(cwd, path) {
+	const absoluteCwd = isAbsolute(cwd) ? cwd : `${process.cwd()}${sep}${cwd}`;
+	const raw = isAbsolute(path) ? path : `${absoluteCwd}${sep}${path}`;
+	const physicalSpelling = /(?:^|[\\/])\.\.(?:[\\/]|$)/u.test(raw) ? raw : resolve(cwd, path);
+	/* v8 ignore next -- Native Windows tests cover DOS drive-relative resolution; POSIX preserves physical traversal. */
+	return process.platform === "win32" ? resolve(cwd, path) : physicalSpelling;
+}
+/**
 * Resolve a path to its absolute display path and realpath identity. For a missing target,
 * realpath the nearest existing ancestor and append the missing suffix, preserving identity
 * across symlinked ancestors before and after creation.
@@ -152,11 +166,11 @@ function versionOf(info) {
 */
 async function resolveLocalTarget(cwd, path) {
 	if (path.trim().length === 0) throw new FsError("file_path must be a non-empty string", "FS_NOT_FOUND");
-	const displayPath = resolve(cwd, path);
+	const displayPath = localDisplayPath(cwd, path);
 	try {
 		return {
 			displayPath,
-			targetKey: FsTargetKey(await realpath(displayPath))
+			targetKey: FsTargetKey(await realpath$1(displayPath))
 		};
 	} catch (error) {
 		/* v8 ignore next -- Windows reports this case as ENOENT and repairs it in the ancestor walk below. */
@@ -167,7 +181,9 @@ async function resolveLocalTarget(cwd, path) {
 	const missing = [basename(displayPath)];
 	let ancestor = dirname(displayPath);
 	while (true) try {
-		const realAncestor = await realpath(ancestor);
+		const realAncestor = await realpath$1(ancestor);
+		/* v8 ignore next -- POSIX rejects this traversal; Windows normalizes parent segments before filesystem lookup. */
+		if (missing.includes("..")) throw new FsError(`cannot resolve "${displayPath}": parent traversal crosses a missing directory`, "FS_NOT_FOUND");
 		/* v8 ignore start -- native Windows coverage exercises this repair; POSIX reports ENOTDIR before this point. */
 		if (process.platform === "win32") {
 			if (!(await stat(realAncestor)).isDirectory()) throw new FsError(`cannot resolve "${displayPath}": a parent path segment is not a directory`, "FS_NOT_FOUND");
@@ -254,7 +270,7 @@ function listingIoError(displayPath, error) {
 async function resolveListedChildTarget(parent, name) {
 	const identity = await resolveLocalTarget(parent.targetKey, name);
 	return {
-		displayPath: join(parent.displayPath, name),
+		displayPath: localDisplayPath(parent.displayPath, name),
 		targetKey: identity.targetKey
 	};
 }
@@ -301,7 +317,7 @@ async function listDirectory(target, signal) {
 				...childInfo?.type === "file" ? { size: childInfo.size } : {}
 			});
 		} catch (error) {
-			throw listingIoError(join(target.displayPath, entry.name), error);
+			throw listingIoError(localDisplayPath(target.displayPath, entry.name), error);
 		}
 		throwIfAborted(signal, "list");
 	}
@@ -770,7 +786,7 @@ var LocalFileSystem = class extends FileSystem {
 	async lstat(path, opts, signal) {
 		if (signal?.aborted) throw new FsError("lstat aborted", "FS_ABORTED");
 		if (path.trim().length === 0) throw new FsError("file_path must be a non-empty string", "FS_NOT_FOUND");
-		const info = await probeNoFollow(resolve(opts?.cwd ?? this.config.cwd, path));
+		const info = await probeNoFollow(localDisplayPath(opts?.cwd ?? this.config.cwd, path));
 		if (signal?.aborted) throw new FsError("lstat aborted", "FS_ABORTED");
 		if (!info) return void 0;
 		return {

package/lib/types/fsio.d.ts

@@ -64,6 +64,13 @@ export interface LocalDirEntry {
     version?: FsVersion;
     size?: number;
 }
+/**
+ * Anchor a path using native drive semantics and POSIX physical parent traversal.
+ * @param cwd - provider base directory for relative paths.
+ * @param path - non-empty requested path.
+ * @returns absolute display spelling shared by target resolution and no-follow metadata.
+ */
+export declare function localDisplayPath(cwd: string, path: string): string;
 /**
  * Resolve a path to its absolute display path and realpath identity. For a missing target,
  * realpath the nearest existing ancestor and append the missing suffix, preserving identity

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-fs-local",
   "description": "Local-filesystem implementation of the DeepSeek Harness filesystem seam (ctx.fs)",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,7 +27,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
@@ -35,8 +35,8 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }