@deepseek-ai/dsh-util-workspace-path 0.1.7-alpha.2 → 0.1.7-rc.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/util/workspace-path/README.md
-README.md: ab7787f3649c8f75a0f0e0745bc78ea32edb5925
-README.zh.md: 270c79f7bb57def13a7656e8f76f900c1e094f4f
+README.md: 2de3157ee8bbe5ea216be303c1a1520d4b92126c
+README.zh.md: b46402b0ecf4025224768a29af1ea984ff7d497f

package/README.md

@@ -26,6 +26,8 @@ A resource address is `dsh-resource://<type>/…`, and the type — the URI host
 
 `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`.
 
+`fileMediaUrl(base, path)` builds an authenticated file-route URL from an already-decoded absolute path. It preserves literal percent signs and deployment prefixes, and rejects non-HTTP application bases, relative paths, network-path prefixes, and control characters. Markdown owners decode authored URLs before calling it; native file-card paths are passed unchanged.
+
 -----
 
 ## Known Limitations and Deferred Work

package/README.zh.md

@@ -26,6 +26,8 @@ kind: "package-library"
 
 `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`。
 
+`fileMediaUrl(base, path)` 从已解码的绝对路径生成带认证文件路由的 URL，保留字面量百分号与部署前缀，并拒绝非 HTTP 应用基址、相对路径、网络路径前缀和控制字符。Markdown 调用方先解码所写 URL；原生文件卡片路径原样传入。
+
 -----
 
 ## 已知限制与暂缓事项

package/lib/index.js

@@ -186,5 +186,15 @@ function relativizeToCwd(text, cwd) {
 	if (text.startsWith(`${root}/`) || text.startsWith(`${root}\\`)) return text.slice(root.length + 1);
 	return text;
 }
+/**
+* Address a decoded absolute file path through the authenticated file route.
+* @param base - HTTP(S) application base, including its deployment prefix.
+* @param path - Native file path; URL escapes in authored Markdown must already be decoded.
+* @returns File URL, or undefined for unsupported transports and non-absolute paths.
+*/
+function fileMediaUrl(base, path) {
+	if (!/^https?:/u.test(base) || !isAbsoluteWorkspacePath(path) || /^[/\\]{2}/u.test(path) || /[\u0000-\u001f\u007f]/u.test(path)) return void 0;
+	return new URL(`api/file?path=${encodeURIComponent(path)}`, base).href;
+}
 //#endregion
-export { abbreviateHomePath, absoluteFileAddress, fileAddressFor, isAbsoluteWorkspacePath, parseFileAddress, pathPartsOf, relativizeToCwd, resolveWorkspacePath, sessionFileAddress, workspaceTitleOf };
+export { abbreviateHomePath, absoluteFileAddress, fileAddressFor, fileMediaUrl, isAbsoluteWorkspacePath, parseFileAddress, pathPartsOf, relativizeToCwd, resolveWorkspacePath, sessionFileAddress, workspaceTitleOf };

package/lib/types/index.d.ts

@@ -57,4 +57,11 @@ export declare function fileAddressFor(sessionId: string, cwd: string | undefine
  * @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;
+/**
+ * Address a decoded absolute file path through the authenticated file route.
+ * @param base - HTTP(S) application base, including its deployment prefix.
+ * @param path - Native file path; URL escapes in authored Markdown must already be decoded.
+ * @returns File URL, or undefined for unsupported transports and non-absolute paths.
+ */
+export declare function fileMediaUrl(base: string, path: string): string | undefined;
 //# 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.7-alpha.2",
+  "version": "0.1.7-rc.1",
   "publishConfig": {
     "access": "public"
   },