@deepseek-ai/dsh-util-workspace-path 0.1.3-alpha.2 → 0.1.5-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/util/workspace-path/README.md
-README.md: 1b09bda74c8836655789c57fa05d03a2892c16b9
-README.zh.md: 25128e5fec504e1724f5cc7952fed976985912d5
+README.md: ab7787f3649c8f75a0f0e0745bc78ea32edb5925
+README.zh.md: 270c79f7bb57def13a7656e8f76f900c1e094f4f

package/README.md

@@ -9,15 +9,25 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Browser-safe path helpers shared by Workspace-facing client and controller packages. The package joins Workspace-relative paths, abbreviates POSIX home directories for display, and derives Workspace titles from POSIX or Windows paths. It has no Cordis service or runtime state.
+Browser-safe path helpers shared by Workspace-facing client and controller packages. The package joins Workspace-relative paths, abbreviates POSIX home directories for display, derives Workspace titles from POSIX or Windows paths, splits a path into its directories and final segment for display, and owns the `dsh-resource://file/…` address grammar that names a workspace file across the Sidebar and the resource model. `relativizeToCwd` removes the workspace prefix for display while preserving paths outside that directory. It has no Cordis service or runtime state.
 
 ## Table of Contents
 
+- [File addresses](#file-addresses)
 - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
 - [Dev Note](#dev-note)
 
 -----
 
+<a id="file-addresses"></a>
+## File addresses
+
+A resource address is `dsh-resource://<type>/…`, and the type — the URI host — is the resource protocol key (`file`, or one a plugin declares in `ResourceProtocolMap`); any other scheme is a navigation protocol, defined elsewhere. `dsh-resource://file/session/<sessionId>/<path>` names the Session that authorizes the Host read and a workspace-relative or absolute path. Leading slashes remain part of the path: `/etc/hosts` is `dsh-resource://file/session/s//etc/hosts`, a Windows drive is `dsh-resource://file/session/s/C:/x/y.txt`, and UNC is `dsh-resource://file/session/s///server/share/y.txt`. The Host resolves paths and enforces access. The `absolute/<path>` form remains parseable but carries no authorizing Session, so the file provider cannot read it and Preview does not claim it; neither current nor Tab Session is borrowed. The grammar lives in [`src/file-address.ts`](src/file-address.ts); the path helpers stay in [`src/index.ts`](src/index.ts), which re-exports it.
+
+`sessionFileAddress(sessionId, path)` normalizes `\` to `/` and drops leading `./`, but preserves leading `/` characters. Every id and path segment is component-encoded with `:` kept literal. `fileAddressFor(sessionId, cwd, path)` always builds a Session address: paths inside `cwd` become relative; other absolute paths, including when `cwd` is unknown, stay absolute within that Session address. `absoluteFileAddress(absolutePath)` builds only the Session-less form. `parseFileAddress(address)` checks the exact file-address prefix, ignores query and fragment suffixes, decodes each segment, and returns `{ scope, sessionId, path }` for a Session address or `{ scope, path }` for the Session-less form. Another type or scheme, an unknown scope, a missing id or path, or a malformed escape returns `undefined`.
+
+-----
+
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>

package/README.zh.md

@@ -9,15 +9,25 @@ kind: "package-library"
 
 ## 概述
 
-供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录，以及从 POSIX 或 Windows 路径提取 Workspace 标题；它不提供 Cordis service，也不持有运行时状态。
+供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录、从 POSIX 或 Windows 路径提取 Workspace 标题、把路径拆成目录部分与末段供展示，并拥有在 Sidebar 与资源模型之间命名工作区文件的 `dsh-resource://file/…` 地址语法。`relativizeToCwd` 在显示时省略工作区前缀，并保留该目录以外的路径。它不提供 Cordis service，也不持有运行时状态。
 
 ## 目录
 
+- [文件地址](#file-addresses)
 - [已知限制与暂缓事项](#known-limitations-and-deferred-work)
 - [开发备注](#dev-note)
 
 -----
 
+<a id="file-addresses"></a>
+## 文件地址
+
+资源地址 = `dsh-resource://<type>/…`，type（URI 的 host）即资源协议键（`file`，或插件在 `ResourceProtocolMap` 中声明的键）；其他 scheme 属导航协议，另行定义。`dsh-resource://file/session/<sessionId>/<path>` 指定授权 Host 读取的 Session，以及工作区相对或绝对路径。前导斜杠保留在路径中：`/etc/hosts` 对应 `dsh-resource://file/session/s//etc/hosts`，Windows 盘符对应 `dsh-resource://file/session/s/C:/x/y.txt`，UNC 对应 `dsh-resource://file/session/s///server/share/y.txt`。Host 解析路径并执行访问检查。`absolute/<path>` 形式仍可解析，但不携带授权 Session，因此 file 提供方不能读取，Preview 也不认领；两者均不借用当前或 Tab Session。语法住在 [`src/file-address.ts`](src/file-address.ts)；路径辅助函数留在 [`src/index.ts`](src/index.ts) 并再导出它。
+
+`sessionFileAddress(sessionId, path)` 将 `\` 归一为 `/`，去掉前导 `./`，但保留前导 `/` 字符。id 和每个路径段都做组件编码，`:` 保持字面。`fileAddressFor(sessionId, cwd, path)` 始终构造 Session 地址：`cwd` 内的路径转为相对路径；其他绝对路径（包括 `cwd` 未知时）仍作为该 Session 地址内的绝对路径。`absoluteFileAddress(absolutePath)` 只构造不带 Session 的形式。`parseFileAddress(address)` 检查精确的文件地址前缀、忽略查询与片段后缀、逐段解码，并为 Session 地址返回 `{ scope, sessionId, path }`，为不带 Session 的形式返回 `{ scope, path }`。其他 type 或 scheme、未知作用域、缺 id 或路径，或错误转义都返回 `undefined`。
+
+-----
+
 ## 已知限制与暂缓事项
 
 <a id="known-limitations-and-deferred-work"></a>

package/lib/index.js

@@ -1,3 +1,85 @@
+//#region lib/types/file-address.js
+/**
+* The `dsh-resource://file/…` address grammar: how a file is named across the
+* Sidebar and the resource model, built and parsed without touching a
+* filesystem.
+* @module
+*/
+/** The scheme and type every file address opens with. */
+const FILE_ADDRESS_PREFIX = "dsh-resource://file/";
+/** Component-encode one id or path segment, keeping `:` literal for drive letters. */
+function encodeSegment(segment) {
+	return encodeURIComponent(segment).replace(/%3A/gi, ":");
+}
+/** Encode a `/`-separated path segment by segment. */
+function encodePath(path) {
+	return path.split("/").map(encodeSegment).join("/");
+}
+/** Whether a decoded first path segment is a Windows drive (`C:`). */
+function isDriveSegment(segment) {
+	return segment !== void 0 && /^[A-Za-z]:$/.test(segment);
+}
+/**
+* Build the address of a file read through one Session.
+* @param sessionId - the Session whose Host workspace resolves the path.
+* @param path - absolute or workspace-relative path; backslashes are normalized to `/`, and leading `./` prefixes are dropped.
+* @returns the `dsh-resource://file/session/<sessionId>/<path>` address.
+*/
+function sessionFileAddress(sessionId, path) {
+	const normalized = path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "");
+	return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`;
+}
+/**
+* Build the address of a file by its absolute path.
+* @param path - absolute path; backslashes are normalized to `/` and the leading `/` is dropped,
+*   except that a UNC path (`\\server\share`) keeps one empty first segment.
+* @returns the `dsh-resource://file/absolute/<path>` address.
+*/
+function absoluteFileAddress(path) {
+	const normalized = path.replace(/\\/g, "/");
+	const unc = normalized.startsWith("//");
+	const absolute = normalized.replace(/^\/+/, "");
+	return `${FILE_ADDRESS_PREFIX}absolute/${unc ? "/" : ""}${encodePath(absolute)}`;
+}
+/**
+* Read a file address back into its parts without resolving `.` or `..`.
+* Query and fragment suffixes are ignored; encoded path segments are decoded.
+* @param address - a candidate address.
+* @returns the parts, or `undefined` when the string is not a `dsh-resource://file/` URI in a known scope with a path, or a segment is not validly encoded.
+*/
+function parseFileAddress(address) {
+	try {
+		if (!address.startsWith(FILE_ADDRESS_PREFIX)) return void 0;
+		const end = address.search(/[?#]/);
+		const [scope, ...rest] = address.slice(20, end === -1 ? void 0 : end).split("/");
+		if (scope === "session") {
+			const [id, ...segments] = rest;
+			if (id === void 0 || id === "" || segments.length === 0) return void 0;
+			return {
+				scope,
+				sessionId: decodeURIComponent(id),
+				path: segments.map(decodeURIComponent).join("/")
+			};
+		}
+		if (scope === "absolute") {
+			const unc = rest[0] === "" && rest.length > 1;
+			const segments = (unc ? rest.slice(1) : rest).map(decodeURIComponent);
+			if (segments.length === 0 || segments[0] === "") return void 0;
+			if (unc) return {
+				scope,
+				path: `//${segments.join("/")}`
+			};
+			return {
+				scope,
+				path: isDriveSegment(segments[0]) ? segments.join("/") : `/${segments.join("/")}`
+			};
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Browser-safe Workspace path and display helpers.
@@ -8,13 +90,21 @@ function isWindowsStylePath(value) {
 	return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith("\\\\");
 }
 /**
+* Whether a path is absolute in either spelling the Host accepts: POSIX (`/a/b`) or Windows drive or UNC.
+* @param path - the path to classify.
+* @returns `true` for an absolute path; `false` for a Workspace-relative one.
+*/
+function isAbsoluteWorkspacePath(path) {
+	return path.startsWith("/") || isWindowsStylePath(path);
+}
+/**
 * Resolve a Workspace-relative path into the Host-facing spelling used by path operations.
 * @param cwd - Session Workspace root, when known.
 * @param path - Absolute or Workspace-relative path.
 * @returns an absolute path when a Workspace root is available, otherwise the original path.
 */
 function resolveWorkspacePath(cwd, path) {
-	if (path.startsWith("/") || isWindowsStylePath(path)) return path;
+	if (isAbsoluteWorkspacePath(path)) return path;
 	if (cwd === void 0 || cwd === "") return path;
 	const separator = isWindowsStylePath(cwd) && cwd.includes("\\") ? "\\" : "/";
 	return `${cwd.replace(/[/\\]+$/, "")}${separator}${path.replace(/^[/\\]+/, "")}`;
@@ -45,5 +135,56 @@ function workspaceTitleOf(path) {
 	const separator = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
 	return trimmed.slice(separator + 1);
 }
+/**
+* Split a path for display: the directories through their last separator, and
+* the final segment after it. Both `/` and `\` separate, so a Windows path
+* splits where its own segments end; trailing separators are dropped first, so
+* a directory path names its own last segment. A path with no separator, or a
+* separator-only path, is all name.
+* @param path - file or directory path using POSIX or Windows separators.
+* @returns the directory prefix (possibly empty) and the final segment.
+*/
+function pathPartsOf(path) {
+	const trimmed = path.replace(/[/\\]+$/, "");
+	if (trimmed === "") return {
+		directory: "",
+		name: path
+	};
+	const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\")) + 1;
+	return {
+		directory: trimmed.slice(0, cut),
+		name: trimmed.slice(cut)
+	};
+}
+/**
+* The address for a path as a caller holds it: a relative path, or an absolute
+* path inside the Session's workspace, becomes a `session`-scoped address; an
+* absolute path outside it, or one whose workspace root is unknown, keeps its
+* absolute path in that Session's address.
+* @param sessionId - the Session the path is read in.
+* @param cwd - that Session's workspace root, when known.
+* @param path - absolute or workspace-relative path, in either separator spelling.
+* @returns the `dsh-resource://file/…` address.
+*/
+function fileAddressFor(sessionId, cwd, path) {
+	const normalized = path.replace(/\\/g, "/");
+	if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized);
+	const root = cwd === void 0 ? "" : cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+	if (root !== "" && normalized === root) return sessionFileAddress(sessionId, "");
+	if (root !== "" && normalized.startsWith(`${root}/`)) return sessionFileAddress(sessionId, normalized.slice(root.length + 1));
+	return sessionFileAddress(sessionId, normalized);
+}
+/**
+* Strip the workspace root from a workspace-rooted absolute path (display only).
+* @param text - the path to shorten.
+* @param cwd - session workspace root; absent or empty leaves the path unchanged.
+* @returns the path relative to the workspace root, or unchanged when it is not rooted there.
+*/
+function relativizeToCwd(text, cwd) {
+	if (cwd === void 0 || cwd === "") return text;
+	const root = cwd.replace(/[/\\]+$/, "");
+	if (text.startsWith(`${root}/`) || text.startsWith(`${root}\\`)) return text.slice(root.length + 1);
+	return text;
+}
 //#endregion
-export { abbreviateHomePath, resolveWorkspacePath, workspaceTitleOf };
+export { abbreviateHomePath, absoluteFileAddress, fileAddressFor, isAbsoluteWorkspacePath, parseFileAddress, pathPartsOf, relativizeToCwd, resolveWorkspacePath, sessionFileAddress, workspaceTitleOf };

package/lib/types/file-address.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `dsh-resource://file/…` address grammar: how a file is named across the
+ * Sidebar and the resource model, built and parsed without touching a
+ * filesystem.
+ * @module
+ */
+/**
+ * A file resource address, in one of two scopes.
+ *
+ * Every resource address is `dsh-resource://<type>/…`, the URI host naming the
+ * resource protocol; for `file` the path opens with the scope:
+ *
+ * - `dsh-resource://file/session/<sessionId>/<path>` names a file by its path,
+ *   relative to that Session's workspace root or absolute; the
+ *   Host resolves it against the root it holds for the Session.
+ * - `dsh-resource://file/absolute/<path>` names a file by its absolute path with
+ *   the leading `/` dropped (`dsh-resource://file/absolute/home/ys/notes.txt`;
+ *   Windows `dsh-resource://file/absolute/C:/x/y.txt`; a UNC path keeps an empty
+ *   first segment, `dsh-resource://file/absolute//server/share/x.txt`). It carries
+ *   no Session.
+ *
+ * Every id and path segment is component-encoded, so a name carrying `#`, `?`,
+ * or a space survives the round trip; `:` stays literal so a drive letter reads
+ * as written.
+ */
+export type FileAddress = {
+    readonly scope: 'session';
+    /** The Session whose Host workspace resolves the path. */
+    readonly sessionId: string;
+    /** Absolute or workspace-relative `/`-separated path; empty for the workspace root itself. */
+    readonly path: string;
+} | {
+    readonly scope: 'absolute';
+    /** Absolute `/`-separated path: `/a/b` on POSIX, `C:/a/b` for a Windows drive, `//server/share/a` for a UNC path. */
+    readonly path: string;
+};
+/**
+ * Build the address of a file read through one Session.
+ * @param sessionId - the Session whose Host workspace resolves the path.
+ * @param path - absolute or workspace-relative path; backslashes are normalized to `/`, and leading `./` prefixes are dropped.
+ * @returns the `dsh-resource://file/session/<sessionId>/<path>` address.
+ */
+export declare function sessionFileAddress(sessionId: string, path: string): string;
+/**
+ * Build the address of a file by its absolute path.
+ * @param path - absolute path; backslashes are normalized to `/` and the leading `/` is dropped,
+ *   except that a UNC path (`\\server\share`) keeps one empty first segment.
+ * @returns the `dsh-resource://file/absolute/<path>` address.
+ */
+export declare function absoluteFileAddress(path: string): string;
+/**
+ * Read a file address back into its parts without resolving `.` or `..`.
+ * Query and fragment suffixes are ignored; encoded path segments are decoded.
+ * @param address - a candidate address.
+ * @returns the parts, or `undefined` when the string is not a `dsh-resource://file/` URI in a known scope with a path, or a segment is not validly encoded.
+ */
+export declare function parseFileAddress(address: string): FileAddress | undefined;
+//# sourceMappingURL=file-address.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,9 @@
 /**
- * Browser-safe Workspace path and display helpers.
- * @module @deepseek-ai/dsh-util-workspace-path
+ * Whether a path is absolute in either spelling the Host accepts: POSIX (`/a/b`) or Windows drive or UNC.
+ * @param path - the path to classify.
+ * @returns `true` for an absolute path; `false` for a Workspace-relative one.
  */
+export declare function isAbsoluteWorkspacePath(path: string): boolean;
 /**
  * Resolve a Workspace-relative path into the Host-facing spelling used by path operations.
  * @param cwd - Session Workspace root, when known.
@@ -23,4 +25,36 @@ export declare function abbreviateHomePath(path: string, home?: string): string;
  * @returns the final segment, or an empty string for a separator-only path.
  */
 export declare function workspaceTitleOf(path: string): string;
+/**
+ * Split a path for display: the directories through their last separator, and
+ * the final segment after it. Both `/` and `\` separate, so a Windows path
+ * splits where its own segments end; trailing separators are dropped first, so
+ * a directory path names its own last segment. A path with no separator, or a
+ * separator-only path, is all name.
+ * @param path - file or directory path using POSIX or Windows separators.
+ * @returns the directory prefix (possibly empty) and the final segment.
+ */
+export declare function pathPartsOf(path: string): {
+    readonly directory: string;
+    readonly name: string;
+};
+export * from './file-address.ts';
+/**
+ * The address for a path as a caller holds it: a relative path, or an absolute
+ * path inside the Session's workspace, becomes a `session`-scoped address; an
+ * absolute path outside it, or one whose workspace root is unknown, keeps its
+ * absolute path in that Session's address.
+ * @param sessionId - the Session the path is read in.
+ * @param cwd - that Session's workspace root, when known.
+ * @param path - absolute or workspace-relative path, in either separator spelling.
+ * @returns the `dsh-resource://file/…` address.
+ */
+export declare function fileAddressFor(sessionId: string, cwd: string | undefined, path: string): string;
+/**
+ * Strip the workspace root from a workspace-rooted absolute path (display only).
+ * @param text - the path to shorten.
+ * @param cwd - session workspace root; absent or empty leaves the path unchanged.
+ * @returns the path relative to the workspace root, or unchanged when it is not rooted there.
+ */
+export declare function relativizeToCwd(text: string, cwd: string | undefined): string;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-util-workspace-path",
   "description": "Browser-safe Workspace path and display helpers",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },