@deepseek-ai/dsh-util-workspace-path 0.1.5-alpha.1 → 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: 0b820992dffe0ce52530f45b01fa73ad8f1c9a23
-README.zh.md: 5648d9e37f1fd6bde8a8c0237051c3f801b01a72
+README.md: ab7787f3649c8f75a0f0e0745bc78ea32edb5925
+README.zh.md: 270c79f7bb57def13a7656e8f76f900c1e094f4f

package/README.md

@@ -9,7 +9,7 @@ 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, derives Workspace titles from POSIX or Windows paths, and owns the `dsh-resource://file/…` address grammar that names a workspace file across the Sidebar and the resource model. 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
 
@@ -22,9 +22,9 @@ Browser-safe path helpers shared by Workspace-facing client and controller packa
 <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. A file address has one of two scopes. `dsh-resource://file/session/<sessionId>/<path>` names a file by its path relative to that Session's workspace root (`dsh-resource://file/session/abc123/src/notes.txt`), which the Host resolves 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` on POSIX, `dsh-resource://file/absolute/C:/x/y.txt` for a Windows drive, `dsh-resource://file/absolute//server/share/y.txt` for a UNC path, whose empty first segment keeps its identity); it carries no Session, so the reader's own Session resolves it, and the Host's workspace confinement still applies. 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.
+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, relativePath)` and `absoluteFileAddress(absolutePath)` build one: `\` becomes `/`, a leading `./` or `/` is dropped, and every id and path segment is component-encoded with `:` kept literal, so `#`, `?`, and spaces in a name survive while a drive letter reads as written. `fileAddressFor(sessionId, cwd, path)` chooses the scope for a path as a caller holds it: a relative path, or an absolute path inside `cwd`, becomes `session`-relative; any other absolute path becomes `absolute`. `parseFileAddress(address)` reads one back through `new URL()`: the scheme must be `dsh-resource` and the host exactly `file`; a `session` address yields `{ scope, sessionId, path }` with the workspace-relative path, an `absolute` address yields `{ scope, path }` with the leading `/` restored (`//` for a UNC path) unless the path starts with a drive letter. It returns `undefined` for another type or scheme, an unknown scope, a missing id or path, a non-URL, or a malformed escape — the caller decides whether that is a failure.
+`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`.
 
 -----
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录、从 POSIX 或 Windows 路径提取 Workspace 标题，并拥有在 Sidebar 与资源模型之间命名工作区文件的 `dsh-resource://file/…` 地址语法；它不提供 Cordis service，也不持有运行时状态。
+供 Workspace 相关客户端和控制器包共享、可在浏览器使用的路径辅助函数。该包负责拼接 Workspace 相对路径、缩写用于展示的 POSIX 主目录、从 POSIX 或 Windows 路径提取 Workspace 标题、把路径拆成目录部分与末段供展示，并拥有在 Sidebar 与资源模型之间命名工作区文件的 `dsh-resource://file/…` 地址语法。`relativizeToCwd` 在显示时省略工作区前缀，并保留该目录以外的路径。它不提供 Cordis service，也不持有运行时状态。
 
 ## 目录
 
@@ -22,9 +22,9 @@ kind: "package-library"
 <a id="file-addresses"></a>
 ## 文件地址
 
-资源地址 = `dsh-resource://<type>/…`，type（URI 的 host）即资源协议键（`file`，或插件在 `ResourceProtocolMap` 中声明的键）；其他 scheme 属导航协议，另行定义。文件地址有两种作用域。`dsh-resource://file/session/<sessionId>/<path>` 以相对该 Session 工作区根的路径命名文件（`dsh-resource://file/session/abc123/src/notes.txt`），由 Host 对它为该 Session 持有的根解析。`dsh-resource://file/absolute/<path>` 以去掉前导 `/` 的绝对路径命名文件（POSIX 上为 `dsh-resource://file/absolute/home/ys/notes.txt`，Windows 盘符为 `dsh-resource://file/absolute/C:/x/y.txt`，UNC 路径为 `dsh-resource://file/absolute//server/share/y.txt`，其空的首段保留 UNC 身份）；它不带 Session，由读者自己的 Session 解析，Host 的工作区限制照样适用。语法住在 [`src/file-address.ts`](src/file-address.ts)；路径辅助函数留在 [`src/index.ts`](src/index.ts) 并再导出它。
+资源地址 = `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, relativePath)` 与 `absoluteFileAddress(absolutePath)` 构造地址：`\` 归一为 `/`，去掉前导 `./` 或 `/`，id 与每个路径段做组件编码但 `:` 保持字面，因此名字里的 `#`、`?`、空格都能保留，盘符也照原样可读。`fileAddressFor(sessionId, cwd, path)` 按调用方手里的路径选作用域：相对路径或落在 `cwd` 内的绝对路径成为 `session` 相对地址，其他绝对路径成为 `absolute` 地址。`parseFileAddress(address)` 用 `new URL()` 读回：scheme 必须是 `dsh-resource`、host 必须恰为 `file`；`session` 地址得到 `{ scope, sessionId, path }`（path 为工作区相对路径），`absolute` 地址得到 `{ scope, path }` 并还原前导 `/`（UNC 路径还原为 `//`），以盘符开头者除外。对其他 type 或 scheme、未知作用域、缺 id 或路径、非 URL、或转义格式错误的输入返回 `undefined`，是否算失败由调用方决定。
+`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`。
 
 -----
 

package/lib/index.js

@@ -20,14 +20,14 @@ function isDriveSegment(segment) {
 	return segment !== void 0 && /^[A-Za-z]:$/.test(segment);
 }
 /**
-* Build the address of a file inside one Session's workspace.
-* @param sessionId - the Session whose workspace root the path is relative to.
-* @param path - workspace-relative path; backslashes are normalized to `/`, and a leading `./` or `/` is dropped.
+* 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 relative = path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
-	return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(relative)}`;
+	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.
@@ -42,15 +42,16 @@ function absoluteFileAddress(path) {
 	return `${FILE_ADDRESS_PREFIX}absolute/${unc ? "/" : ""}${encodePath(absolute)}`;
 }
 /**
-* Read a file address back into its parts.
+* 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 {
-		const url = new URL(address);
-		if (url.protocol !== "dsh-resource:" || url.host !== "file") return void 0;
-		const [, scope, ...rest] = url.pathname.split("/");
+		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;
@@ -135,10 +136,31 @@ function workspaceTitleOf(path) {
 	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, becomes an
-* `absolute`-scoped address.
+* 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.
@@ -150,7 +172,19 @@ function fileAddressFor(sessionId, cwd, path) {
 	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 absoluteFileAddress(normalized);
+	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, absoluteFileAddress, fileAddressFor, isAbsoluteWorkspacePath, parseFileAddress, resolveWorkspacePath, sessionFileAddress, workspaceTitleOf };
+export { abbreviateHomePath, absoluteFileAddress, fileAddressFor, isAbsoluteWorkspacePath, parseFileAddress, pathPartsOf, relativizeToCwd, resolveWorkspacePath, sessionFileAddress, workspaceTitleOf };

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

@@ -10,15 +10,14 @@
  * 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 (`src/a.ts`, no leading `/`); the
+ * - `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: the reader's own Session resolves it, and the Host's workspace
- *   confinement still applies.
+ *   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
@@ -26,9 +25,9 @@
  */
 export type FileAddress = {
     readonly scope: 'session';
-    /** The Session whose workspace root the path is relative to. */
+    /** The Session whose Host workspace resolves the path. */
     readonly sessionId: string;
-    /** Workspace-relative `/`-separated path, no leading `/`; empty for the root itself. */
+    /** Absolute or workspace-relative `/`-separated path; empty for the workspace root itself. */
     readonly path: string;
 } | {
     readonly scope: 'absolute';
@@ -36,9 +35,9 @@ export type FileAddress = {
     readonly path: string;
 };
 /**
- * Build the address of a file inside one Session's workspace.
- * @param sessionId - the Session whose workspace root the path is relative to.
- * @param path - workspace-relative path; backslashes are normalized to `/`, and a leading `./` or `/` is dropped.
+ * 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;
@@ -50,7 +49,8 @@ export declare function sessionFileAddress(sessionId: string, path: string): str
  */
 export declare function absoluteFileAddress(path: string): string;
 /**
- * Read a file address back into its parts.
+ * 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.
  */

package/lib/types/index.d.ts

@@ -25,16 +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, becomes an
- * `absolute`-scoped address.
+ * 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.5-alpha.1",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },