feat(util): add workspace path helpers

packages/util/workspace-path/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Browser-safe Workspace path and display helpers.
+ * @module @deepseek-ai/dsh-util-workspace-path
+ */
+
+/** Whether a path uses a Windows drive or UNC prefix. */
+function isWindowsStylePath(value: string): boolean {
+  return /^[A-Za-z]:[/\\]/.test(value) || value.startsWith('\\\\')
+}
+
+/**
+ * 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.
+ */
+export function resolveWorkspacePath(cwd: string | undefined, path: string): string {
+  if (path.startsWith('/') || isWindowsStylePath(path)) return path
+  if (cwd === undefined || cwd === '') return path
+  const base = cwd.replace(/[/\\]+$/, '')
+  const relative = path.replace(/^[/\\]+/, '')
+  return `${base}/${relative}`
+}
+
+/**
+ * Abbreviate a POSIX home directory for display.
+ * @param path - Absolute or already-short display path.
+ * @param home - Host account home; absent skips abbreviation.
+ * @returns `~` or `~/…` for the POSIX home and its descendants, otherwise `path`.
+ */
+export function abbreviateHomePath(path: string, home?: string): string {
+  if (home === undefined || home === '') return path
+  if (isWindowsStylePath(path) || isWindowsStylePath(home)) return path
+  const root = home.replace(/\/+$/, '')
+  if (root === '' || root === '/') return path
+  if (path.replace(/\/+$/, '') === root) return '~'
+  if (path.startsWith(`${root}/`)) return `~${path.slice(root.length)}`
+  return path
+}
+
+/**
+ * Read the final non-empty segment of a Workspace path for display.
+ * @param path - Workspace directory path using POSIX or Windows separators.
+ * @returns the final segment, or an empty string for a separator-only path.
+ */
+export function workspaceTitleOf(path: string): string {
+  return path.replace(/[/\\]+$/, '').split(/[/\\]/).pop() ?? ''
+}

packages/util/workspace-path/src/invariant.ts

@@ -0,0 +1,27 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-util-workspace-path`.
+ * @module @deepseek-ai/dsh-util-workspace-path/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-util-workspace-path'
+
+/** Cordis companion plugin name. */
+export const name = 'workspace-path-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: this utility owns no mutable runtime relationship. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */