@deepseek-ai/dsh-api-workspace-files 0.1.6-alpha.1 → 0.1.7-alpha.1

package/lib/index.js

@@ -4,14 +4,11 @@ import { Remote, RemoteError, TypertRemoteService } from "@deepseek-ai/dsh-typer
 import { Deque } from "@deepseek-ai/dsh-deque";
 //#region lib/types/changes.js
 /**
-* Producer of the `changes` stream: every `fs/observed` emission whose target
-* lies inside a generation's workspace root becomes one frame of that
-* generation. Instrumented filesystem operations emit these observations; the
-* operating system is not watched.
-* Each generation acknowledges its observation queue and resolved workspace
-* root with `ready` before emitting any queued or live changes.
+* Target-scoped filesystem watches and `fs/observed` invalidations for `changes`.
+* Each generation sends `ready` after watcher initialization, then reads current
+* target metadata for matching queued and live invalidations.
 */
-/** Owns `fs/observed` observation and every open `changes` generation. */
+/** Owns target watches, instrumented observations, and every open `changes` generation. */
 var WorkspaceChangeFeed = class {
 	ctx;
 	followers = /* @__PURE__ */ new Set();
@@ -21,37 +18,83 @@ var WorkspaceChangeFeed = class {
 		ctx.on("fs/observed", (target, observation) => {
 			for (const follower of this.followers) follower.push([target, observation]);
 		});
-		ctx.effect(() => () => {
-			for (const follower of this.followers) follower.close();
+		ctx.effect(() => async () => {
+			const followers = [...this.followers];
+			await Promise.all(followers.map((follower) => follower.close()));
 			this.followers.clear();
 		}, "workspace-files.changes");
 	}
 	/**
-	* Open one generation reporting observations inside `workspaceRoot`.
+	* Open one target watch; directory targets remain inside `workspaceRoot`.
 	* @param workspaceRoot - the session's workspace root path.
+	* @param path - target path, resolved relative to the workspace root; Host metadata determines its type.
 	* @param signal - generation cancellation.
-	* @returns `ready` after observation is active and the root resolves, then
-	*   observations made after the generation was first pulled, in emission order.
+	* @returns `ready` after watching starts, then current metadata for target invalidations.
 	*/
-	async *follow(workspaceRoot, signal) {
+	async *follow(workspaceRoot, path, signal) {
 		signal.throwIfAborted();
-		const follower = new ChangeFollower();
+		const follower = new ChangeFollower(() => {
+			signal.removeEventListener("abort", cancel);
+			this.followers.delete(follower);
+		});
+		signal = AbortSignal.any([signal, follower.controller.signal]);
+		const aborted = () => signal.aborted;
+		const cancel = () => {
+			follower.close().catch((error) => {
+				this.ctx.logger.error(error);
+			});
+		};
+		signal.addEventListener("abort", cancel, { once: true });
 		this.followers.add(follower);
+		let unwatch;
 		try {
 			const root = await this.ctx.fs.resolve(workspaceRoot, { signal }).catch((error) => {
-				if (signal.aborted) return void 0;
+				if (aborted()) return void 0;
+				throw error;
+			});
+			if (root === void 0 || aborted() || follower.isClosed) return;
+			const target = await this.ctx.fs.resolve(path, {
+				cwd: workspaceRoot,
+				signal
+			}).catch((error) => {
+				if (aborted()) return void 0;
 				throw error;
 			});
-			if (root === void 0 || signal.aborted || follower.isClosed) return;
+			if (target === void 0 || aborted()) return;
+			const stat = async () => {
+				const info = await this.ctx.fs.stat(target, signal).catch((error) => {
+					if (aborted()) return void 0;
+					throw error;
+				});
+				if (info?.type === "directory" && !this.ctx.fs.contains(root, target)) throw new RemoteError("workspace-file/outside-workspace", "Directory is outside the workspace", { path });
+				return info;
+			};
+			await stat();
+			if (aborted()) return;
+			try {
+				unwatch = await this.ctx.fs.watch(target, (error) => {
+					if (error !== void 0) follower.fail(error);
+					else if (!follower.isClosed) follower.push([target]);
+				}, signal);
+				if (follower.error !== void 0) throw follower.error;
+			} catch (error) {
+				if (aborted() && follower.error === void 0) return;
+				const failure = follower.error ?? error;
+				throw new RemoteError("workspace-file/watch-unsupported", failure instanceof Error ? failure.message : String(failure), { path });
+			}
+			follower.initialized.resolve(unwatch);
+			if (aborted()) return;
 			yield { kind: "ready" };
-			for await (const [target, observation] of follower.read(signal)) {
-				if (!this.ctx.fs.contains(root, target)) continue;
+			for await (const [observed] of follower.read()) {
+				if (observed.targetKey !== target.targetKey) continue;
+				const info = await stat();
+				if (aborted()) return;
 				const absolutePath = this.ctx.fs.processPath(target);
 				yield {
 					kind: "change",
-					change: observation.kind === "present" ? {
+					change: info !== void 0 ? {
 						absolutePath,
-						version: observation.version
+						version: info.version
 					} : {
 						absolutePath,
 						absent: true
@@ -59,50 +102,59 @@ var WorkspaceChangeFeed = class {
 				};
 			}
 		} finally {
-			this.followers.delete(follower);
-			follower.close();
+			follower.initialized.resolve(unwatch);
+			await follower.close();
 		}
 	}
 };
 /** One generation's queue: observations wait here until its consumer pulls them. */
 var ChangeFollower = class {
+	release;
+	controller = new AbortController();
+	initialized = Promise.withResolvers();
+	error;
 	queue = new Deque();
 	wake;
 	closed = false;
-	/** Whether the generation was closed while its workspace root resolved. */
+	closing;
+	constructor(release) {
+		this.release = release;
+	}
+	/** Whether this generation has stopped accepting invalidations. */
 	get isClosed() {
 		return this.closed;
 	}
 	push(observed) {
+		if (this.closed) return;
 		this.queue.pushBack(observed);
 		this.wake?.();
 	}
 	close() {
+		if (this.closing !== void 0) return this.closing;
 		this.closed = true;
+		this.closing = this.initialized.promise.then((unwatch) => unwatch?.()).finally(this.release);
+		this.controller.abort();
 		this.wake?.();
+		return this.closing;
+	}
+	fail(error) {
+		this.error = error;
+		this.controller.abort();
 	}
 	/** Drain until closed or aborted; anything still queued then is dropped with the generation. */
-	async *read(signal) {
-		const abort = () => {
-			this.close();
-		};
-		signal.addEventListener("abort", abort, { once: true });
-		if (signal.aborted) abort();
-		try {
-			while (!this.closed) {
-				const observed = this.queue.popFront();
-				if (observed !== void 0) {
-					yield observed;
-					continue;
-				}
-				await new Promise((resolve) => {
-					this.wake = resolve;
-				});
-				this.wake = void 0;
+	async *read() {
+		while (!this.closed) {
+			const observed = this.queue.popFront();
+			if (observed !== void 0) {
+				yield observed;
+				continue;
 			}
-		} finally {
-			signal.removeEventListener("abort", abort);
+			await new Promise((resolve) => {
+				this.wake = resolve;
+			});
+			this.wake = void 0;
 		}
+		if (this.error !== void 0) throw this.error;
 	}
 };
 //#endregion
@@ -248,8 +300,6 @@ let WorkspaceFiles = (() => {
 	let _instanceExtraInitializers = [];
 	let _read_decorators;
 	let _readBytes_decorators;
-	let _readAll_decorators;
-	let _readRelated_decorators;
 	let _stat_decorators;
 	let _list_decorators;
 	let _changes_decorators;
@@ -258,8 +308,6 @@ let WorkspaceFiles = (() => {
 			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
 			_read_decorators = [Remote];
 			_readBytes_decorators = [Remote];
-			_readAll_decorators = [Remote];
-			_readRelated_decorators = [Remote];
 			_stat_decorators = [Remote];
 			_list_decorators = [Remote];
 			_changes_decorators = [Remote({ mode: "stream" })];
@@ -285,28 +333,6 @@ let WorkspaceFiles = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
-			__esDecorate(this, null, _readAll_decorators, {
-				kind: "method",
-				name: "readAll",
-				static: false,
-				private: false,
-				access: {
-					has: (obj) => "readAll" in obj,
-					get: (obj) => obj.readAll
-				},
-				metadata: _metadata
-			}, null, _instanceExtraInitializers);
-			__esDecorate(this, null, _readRelated_decorators, {
-				kind: "method",
-				name: "readRelated",
-				static: false,
-				private: false,
-				access: {
-					has: (obj) => "readRelated" in obj,
-					get: (obj) => obj.readRelated
-				},
-				metadata: _metadata
-			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _stat_decorators, {
 				kind: "method",
 				name: "stat",
@@ -410,75 +436,44 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
-		* Read one byte window of a regular file readable by the filesystem backend: raw
-		* bytes, no text decoding and no binary rejection.
+		* Read a complete regular file or one byte range without text decoding.
 		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-		* @param path - absolute path or path relative to the workspace root; files outside it are allowed.
-		* @param range - the byte window; omitted fields take the window defaults.
+		* @param path - target path, absolute or workspace-relative; relative to the base file's directory when provided.
+		* @param options - optional base file and range; without a range the complete-file cap applies.
 		* @param signal - caller cancellation.
-		* @returns the window in base64, the file's version and size at the stat before it, and whether it reaches the last byte.
+		* @returns native bytes with the file's version and size at the preceding stat, byte offset, and EOF marker.
 		*/
-		async readBytes(workspaceFileScope, path, range, signal) {
-			const { offset, length } = this.resolveWindow(range, path);
-			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
-			const data = await this.ctx.fs.readByteRange(target, {
-				offset,
-				length
-			}, signal);
-			const eof = info.size === void 0 ? data.length < length : offset + data.length >= info.size;
-			return {
-				...this.statOf(target, info),
-				offset,
-				data: Buffer.from(data).toString("base64"),
-				eof
-			};
-		}
-		/**
-		* Read a complete regular file as bytes, subject to the configured full-file cap.
-		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-		* @param path - absolute or workspace-relative file path.
-		* @param signal - caller cancellation.
-		* @returns one complete base64 window with offset zero and eof true; oversized files fail with too-large.
-		*/
-		async readAll(workspaceFileScope, path, signal) {
-			const { target, info } = await this.locateFile(workspaceFileScope, path, signal);
+		async readBytes(workspaceFileScope, path, options, signal) {
+			const window = options.range === void 0 ? void 0 : this.resolveWindow(options.range, path);
+			const resolved = options.baseFile === void 0 ? path : await this.relativePath(workspaceFileScope, options.baseFile, path, signal);
+			const { target, info } = await this.locateFile(workspaceFileScope, resolved, signal);
+			if (window !== void 0) {
+				const { offset, length } = window;
+				const data = await this.ctx.fs.readByteRange(target, window, signal);
+				const eof = info.size === void 0 ? data.length < length : offset + data.length >= info.size;
+				return {
+					...this.statOf(target, info),
+					offset,
+					data,
+					eof
+				};
+			}
 			const limit = this.config.maxFileBytes;
-			if (info.size !== void 0 && info.size > limit) throw new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, {
-				path,
-				limit
-			});
-			const data = await this.ctx.fs.readByteRange(target, {
-				offset: 0,
-				length: limit + 1
-			}, signal);
-			if (data.length > limit) throw new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, {
-				path,
-				limit
+			const data = await this.ctx.fs.readBytes(target, signal, limit).catch((cause) => {
+				if (typeof cause === "object" && cause !== null && "code" in cause && cause.code === "FS_TOO_LARGE") throw new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, {
+					path,
+					limit
+				}, { cause });
+				throw cause;
 			});
 			return {
 				...this.statOf(target, info),
 				offset: 0,
-				data: Buffer.from(data).toString("base64"),
+				data,
 				eof: true
 			};
 		}
 		/**
-		* Read a complete file relative to another file's directory, including outside the workspace.
-		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
-		* @param path - base file, absolute or workspace-relative.
-		* @param relativePath - relative filesystem path, not a URL or absolute path.
-		* @param signal - caller cancellation.
-		* @returns the complete related file using the ordinary file-size and access checks.
-		*/
-		async readRelated(workspaceFileScope, path, relativePath, signal) {
-			const relative = relativePath.replace(/\\/g, "/");
-			if (relative.length === 0 || relative.startsWith("/") || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) throw new RemoteError("gateway/bad-request", "relativePath must be a relative filesystem path", {});
-			const { target } = await this.locateFile(workspaceFileScope, path, signal);
-			const absolute = this.ctx.fs.processPath(target);
-			const paths = absolute.startsWith("/") ? posix : win32;
-			return this.readAll(workspaceFileScope, paths.resolve(paths.dirname(absolute), relative), signal);
-		}
-		/**
 		* Report one regular file's identity, version, and size without its content.
 		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
 		* @param path - absolute path or path relative to the workspace root; files outside it are allowed.
@@ -511,16 +506,24 @@ let WorkspaceFiles = (() => {
 			};
 		}
 		/**
-		* Stream every `fs/observed` observation of a file inside the Session's
-		* workspace. Only instrumented filesystem operations report here; the OS is
-		* not watched.
+		* Watch one file or a directory's direct entries in the Session's filesystem.
+		* Files use the backend's read authority; directories remain workspace-scoped.
 		* @param workspaceFileScope - header-derived workspace root for the Session identity on the wire.
+		* @param path - target path; the Host determines its type and confines directories to the workspace.
 		* @param signal - generation cancellation.
-		* @returns `ready` once the Host observation queue is active and the workspace
-		*   root is resolved, then queued and live observations in emission order.
+		* @returns `ready` once the target watch is active, then current metadata for queued and live invalidations.
+		* @throws RemoteError when watching is unavailable or a directory is outside the workspace.
 		*/
-		changes(workspaceFileScope, signal) {
-			return this.feed.follow(workspaceFileScope.workspaceRoot, signal);
+		changes(workspaceFileScope, path, signal) {
+			return this.feed.follow(workspaceFileScope.workspaceRoot, path, signal);
+		}
+		async relativePath(scope, baseFile, path, signal) {
+			const relative = path.replace(/\\/g, "/");
+			if (relative.length === 0 || relative.startsWith("/") || /^[a-z][a-z\d+.-]*:/iu.test(relative) || relative.includes(NUL)) throw new RemoteError("gateway/bad-request", "path must be relative when baseFile is provided", {});
+			const { target } = await this.locateFile(scope, baseFile, signal);
+			const absolute = this.ctx.fs.processPath(target);
+			const paths = absolute.startsWith("/") ? posix : win32;
+			return paths.resolve(paths.dirname(absolute), relative);
 		}
 		/** Apply the page defaults and caps here, so the request never carries them implicitly. */
 		resolvePage(range) {