@deepseek-ai/dsh-fs-local 0.1.3-alpha.2 → 0.1.5-alpha.1

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: 07fb96d457abd3807e892d37d473e92093078664
-README.zh.md: 4980de0c7fe771f75e38d896644d62c29c352c04
+README.md: 427cf02631f9d56246851f7fc67c92dd662c2a62
+README.zh.md: 7009d9dd853b5443780978036792f10ebc9706b5

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-fs-local` implements the `ctx.fs` filesystem contract ([`dsh-fs`](../fs/README.md)) on the host filesystem: loading it as a plugin populates `ctx.fs` with real file access — resolve, read, list, atomic write, and literal edit against the local machine's files. Relative paths resolve from a configurable base directory, and the same file reached through different paths or symlinks shares one identity. Because this backend shares the host filesystem, it can also map an absolute host path into the process path used by this execution world. Writes are atomic and preserve file permissions; the optional version guard makes stale overwrites fail instead of clobbering. Choose it when a process needs direct, unconfined access to host files; choose `fs-sandbox` when mutations must be confined, or `fs-e2b` when file state belongs 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 or `fs-e2b` for files in a remote execution world.
 
 ## Table of Contents
 
@@ -50,7 +50,7 @@ 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, 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 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.
 
 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.
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-fs-local` 在宿主文件系统上实现 `ctx.fs` 文件系统约定（[`dsh-fs`](../fs/README.zh.md)）：把它作为插件加载后，`ctx.fs` 就拥有真实的文件访问能力——针对本机文件的解析、读取、列出、原子写入与字面量编辑。相对路径从可配置的基准目录解析，经不同路径或符号链接到达的同一文件共享一个身份。由于本后端共享宿主文件系统，它还可以把绝对宿主路径映射为此执行世界使用的进程路径。写入是原子的并保留文件权限；可选版本防护让陈旧覆盖失败而不是静默覆盖。当进程需要直接、不受约束地访问宿主文件时选择它；需要约束变更时选择 `fs-sandbox`，文件状态属于远程执行世界时选择 `fs-e2b`。
+使用 `dsh-fs-local` 可在宿主文件系统上读取、列出、原子写入和编辑文件。相对路径从可配置的基准目录解析，而绝对路径和父目录遍历不受限制。到达同一文件的路径和符号链接共享一个身份。写入保留文件权限，可选版本防护会拒绝陈旧覆盖。直接访问宿主文件时选择本包；需要约束变更时使用 `fs-sandbox`，文件位于远程执行世界时使用 `fs-e2b`。
 
 ## 目录
 
@@ -50,7 +50,7 @@ kind: "package-reference"
 
 ### 你能做什么
 
-完整或流式读取任意普通 UTF-8 文本文件，按你选择的上限读取原始字节，并按稳定名称顺序列出一层目录。原子地创建或替换文件，并原子地应用字面量文本编辑；两个变更操作都按文件串行化，并发写入方绝不会交错。版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。
+完整或流式读取任意普通 UTF-8 文本文件，按你选择的上限或按字节窗口读取原始字节，并按稳定名称顺序列出一层目录。原子地创建或替换文件，并原子地应用字面量文本编辑；两个变更操作都按文件串行化，并发写入方绝不会交错。版本防护是可选的：省略它即无条件创建或覆盖，提供它则在文件自上次观察以来发生变化时失败。
 
 失败是携带稳定错误码的类型化 `FsError`——`FS_NOT_FOUND`、`FS_NOT_TEXT`（二进制内容）、`FS_STALE_VERSION`（自观察以来已变化）、`FS_EDIT_NOT_FOUND` 或 `FS_AMBIGUOUS_EDIT`（无唯一字面量匹配）等——因此调用方依据错误码分支，绝不解析消息文本。带防护的编辑遇到缺失目标时，无论哪种情况都报告 `FS_STALE_VERSION`。
 

package/lib/index.js

@@ -390,6 +390,39 @@ async function readWholeBytes(target, signal, maxBytes, internals = {}) {
 	return Buffer.concat(chunks, bytes);
 }
 /**
+* Read the bytes at `[offset, offset + length)` of a regular file with no
+* decoding or binary rejection. The window is the bound: the stream opens at
+* `offset` and closes after `length` bytes, so no more than the window is ever
+* buffered whatever the file's size; a window at or past the end is empty.
+* @param target - the resolved file to read.
+* @param range - `offset`, the 0-based first byte, and `length`, the largest byte count.
+* @param signal - aborts the read (`FS_ABORTED`).
+* @returns the window's bytes, at most `length` long.
+*/
+async function readByteWindow(target, range, signal) {
+	await statRegularFile(target, "read", signal);
+	if (range.length === 0) return new Uint8Array(0);
+	const stream = createReadStream(target.targetKey, {
+		start: range.offset,
+		end: range.offset + range.length - 1,
+		...signal ? { signal } : {}
+	});
+	const chunks = [];
+	let bytes = 0;
+	try {
+		for await (const chunk of stream) {
+			chunks.push(chunk);
+			bytes += chunk.length;
+		}
+	} catch (error) {
+		/* v8 ignore next 2 -- a mid-stream abort needs cancellation racing an active read; pre-abort is deterministic. */
+		if (isAbortError(error)) throw new FsError("read aborted", "FS_ABORTED");
+		/* v8 ignore next -- any other stream failure needs an I/O fault after a successful stat. */
+		throw error;
+	}
+	return Buffer.concat(chunks, bytes);
+}
+/**
 * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
 * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,
 * cross-chunk UTF-8 decoding), but never holds the whole file in memory.
@@ -764,6 +797,12 @@ var LocalFileSystem = class extends FileSystem {
 			targetKey: target.targetKey
 		}, signal, maxBytes, this.internals);
 	}
+	async readByteRange(target, range, signal) {
+		return readByteWindow({
+			displayPath: target.displayPath,
+			targetKey: target.targetKey
+		}, range, signal);
+	}
 	async listDir(target, signal) {
 		return (await listDirectory({
 			displayPath: target.displayPath,

package/lib/types/fsio.d.ts

@@ -114,6 +114,20 @@ export declare function readWholeText(target: LocalTarget, signal?: AbortSignal)
  * @returns the full raw content, at most `maxBytes` long.
  */
 export declare function readWholeBytes(target: LocalTarget, signal: AbortSignal | undefined, maxBytes: number, internals?: FsIoInternals): Promise<Uint8Array>;
+/**
+ * Read the bytes at `[offset, offset + length)` of a regular file with no
+ * decoding or binary rejection. The window is the bound: the stream opens at
+ * `offset` and closes after `length` bytes, so no more than the window is ever
+ * buffered whatever the file's size; a window at or past the end is empty.
+ * @param target - the resolved file to read.
+ * @param range - `offset`, the 0-based first byte, and `length`, the largest byte count.
+ * @param signal - aborts the read (`FS_ABORTED`).
+ * @returns the window's bytes, at most `length` long.
+ */
+export declare function readByteWindow(target: LocalTarget, range: {
+    offset: number;
+    length: number;
+}, signal?: AbortSignal): Promise<Uint8Array>;
 /**
  * Stream a whole regular UTF-8 text file as decoded text chunks. Same text
  * semantics as {@link readWholeText} (regular-file check, binary/NUL rejection,

package/lib/types/index.d.ts

@@ -53,6 +53,10 @@ export declare class LocalFileSystem extends FileSystem {
     readText(target: FsTarget, signal?: AbortSignal): Promise<string>;
     streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>;
     readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>;
+    readByteRange(target: FsTarget, range: {
+        offset: number;
+        length: number;
+    }, signal?: AbortSignal): Promise<Uint8Array>;
     listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>;
     writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>;
     editText(target: FsTarget, edit: FsEditRequest, expected?: {

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.3-alpha.2",
+  "version": "0.1.5-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,7 +27,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-fs": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
@@ -35,8 +35,8 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-fs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-fs": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.1",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }