Import src/core/folders.ts

This commit is contained in:
QQ 2026-11-11 22:33:35 +08:00
parent c6b31f7225
commit 39e90a1478
1 changed files with 414 additions and 0 deletions

414
src/core/folders.ts Normal file
View File

@ -0,0 +1,414 @@
/**
* Pure folder-list logic for per-workspace multi-root folders.
*
* DSH core gives a workspace exactly ONE canonical directory
* (`WorkspaceView.path`). This module layers a plugin-owned list of EXTRA
* folders on top of it, plus one designated root folder per workspace:
*
* - the canonical directory is always folder #0 (the "base"); it cannot be
* removed and may be the root;
* - `root` is stored only when it names an EXTRA folder — "base is the root"
* is expressed by omitting the key, so the base path is never duplicated
* into the sidecar;
* - a session whose recorded `cwd` lives inside an extra folder belongs to
* that folder, not to the project row.
*
* Everything here is pure and platform-agnostic: it imports no React, no DOM
* and no cordis so plain Node (the verifier, the host route) can load it.
*/
/** Kind of a member folder: a plain local directory, or an SSH-mirrored one. */
export type FolderMemberKind = 'local' | 'remote'
/**
* A folder row that is backed by its OWN DSH workspace ("member").
*
* Plain extra folders ( {@link WorkspaceFolderEntry.folders} ) live inside the
* owner's canonical directory tree and their sessions run with the OWNER's
* workspace id. A member has a directory the owner cannot reach that way — a
* remote (mirror-backed) folder, or a local directory added to a remote project
* — so the platform registers a real workspace for it and the row delegates
* session creation to that workspace id. The member's own workspace row is
* hidden from the sidebar while some entry lists it (see
* {@link absorbedWorkspaceIds}), so the project reads as one project with both
* kinds of folders.
*/
export interface FolderMember {
/** Absolute LOCAL path of the member workspace (its canonical directory). */
readonly path: string
/** Native DSH workspace id backing this folder row. */
readonly workspaceId: string
readonly kind: FolderMemberKind
/** Remote root, when `kind` is 'remote' (`~`, `~/proj`, `/srv/proj`). */
readonly remotePath?: string
/** SSH connection profile id, when `kind` is 'remote'. */
readonly profileId?: string
/** remote-ssh's own record id, when `kind` is 'remote'. */
readonly recordId?: string
/** Display title the platform gave the member workspace. */
readonly title?: string
}
/** Folders attached to one workspace: EXTRA folders only (the base is implicit). */
export interface WorkspaceFolderEntry {
/**
* Plain local extra folders: directories the owner workspace can address
* directly, so their sessions keep the owner's workspace id.
*/
readonly folders: readonly string[]
/** Workspace-backed extra folders (remote mirrors, or local on a remote owner). */
readonly members?: readonly FolderMember[]
readonly root?: string
}
/** The whole `workspace-groups.folders.json` document. */
export interface FoldersDocument {
readonly version: 1
/**
* Monotonic write counter, owned by the host: every accepted PUT bumps it
* and a PUT whose revision does not match the stored one is rejected
* (409), so two windows can no longer silently overwrite each other's
* edits. Absent in documents written before revisions existed — read as 0.
*/
readonly revision?: number
readonly workspaces: Readonly<Record<string, WorkspaceFolderEntry>>
}
/** Canonical empty document, shared so callers need not allocate one each time. */
export const EMPTY_FOLDERS_DOCUMENT: FoldersDocument = { version: 1, revision: 0, workspaces: {} }
/** `C:\…` or `C:/…` — a drive-rooted Windows path. */
const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/u
/** `\\server\share` — a Windows UNC path. */
const WINDOWS_UNC = /^\\\\/u
/** True for both Windows path spellings accepted by the write validator. */
function isWindowsStyle(path: string): boolean {
return WINDOWS_DRIVE.test(path) || WINDOWS_UNC.test(path)
}
/**
* One path with trailing separators removed, spelling preserved (no case
* folding) — the form to STORE. A drive/UNC/root prefix keeps its separator.
* @param path - raw path.
*/
function withoutTrailingSeparator(path: string): string {
if (isWindowsStyle(path)) {
let value = path.replaceAll('/', '\\')
while (value.length > 3 && value.endsWith('\\')) value = value.slice(0, -1)
return value
}
let value = path
while (value.length > 1 && value.endsWith('/')) value = value.slice(0, -1)
return value
}
/**
* Comparison form of one path: trimmed, separator-normalized and, for Windows
* spellings, lower-cased (drive letters and file names are case-insensitive
* there). Trailing separators are dropped except for a drive/UNC/root prefix.
* @param path - raw path as stored or picked.
* @returns the canonical comparison form.
*/
function canonicalPath(path: string): string {
const trimmed = path.trim()
const value = withoutTrailingSeparator(trimmed)
return isWindowsStyle(trimmed) ? value.toLowerCase() : value
}
/**
* Path equality: case-insensitive for Windows-style paths, tolerant of
* trailing separators, exact for POSIX paths.
* @param a - first path.
* @param b - second path.
*/
export function samePath(a: string, b: string): boolean {
return canonicalPath(a) === canonicalPath(b)
}
/**
* Look up the folder entry saved for one workspace.
* @param doc - folders document.
* @param workspaceId - host workspace id.
* @returns the entry, or undefined when the workspace has none.
*/
export function entryFor(doc: FoldersDocument, workspaceId: string): WorkspaceFolderEntry | undefined {
return doc.workspaces[workspaceId]
}
/**
* The workspace's effective folder list, base first. The base cannot be
* duplicated and blank extra entries are dropped.
* @param workspacePath - canonical directory of the workspace.
* @param entry - saved folder entry, if any.
*/
export function effectiveFolders(
workspacePath: string,
entry: WorkspaceFolderEntry | undefined,
): readonly string[] {
const extras: string[] = []
const candidates: string[] = [
...(entry?.folders ?? []),
...(entry?.members ?? []).map(member => member.path),
]
for (const folder of candidates) {
if (folder.trim() === '') continue
if (samePath(folder, workspacePath)) continue
if (extras.some(existing => samePath(existing, folder))) continue
extras.push(folder)
}
return [workspacePath, ...extras]
}
/**
* The member record behind one folder path, when that folder is workspace-backed.
* @param entry - saved folder entry, if any.
* @param path - folder path as stored.
*/
export function memberOf(entry: WorkspaceFolderEntry | undefined, path: string): FolderMember | undefined {
return (entry?.members ?? []).find(member => samePath(member.path, path))
}
/**
* Light canonical form of a REMOTE path (POSIX — the server's filesystem):
* trimmed, trailing slashes removed. Deliberately string-only: the client
* cannot resolve `~` or symlinks; the remote-ssh host canonicalizes fully
* at registration time. This is the second line of defense, catching the
* spelling variants a user can type into the add-cloud-folder dialog.
* @param raw - remote path as typed or as stored.
*/
export function lightRemotePath(raw: string): string {
const trimmed = raw.trim()
return trimmed.length > 1 ? trimmed.replace(/\/+$/, '') : trimmed
}
/**
* Whether two remote paths name the same directory under {@link lightRemotePath}.
* @param a - first remote path.
* @param b - second remote path.
*/
export function sameRemotePath(a: string, b: string): boolean {
return lightRemotePath(a) === lightRemotePath(b)
}
/**
* The member backed by one native workspace id, when one exists.
* @param entry - saved folder entry, if any.
* @param workspaceId - native workspace id backing the member.
*/
export function memberByWorkspaceId(entry: WorkspaceFolderEntry | undefined, workspaceId: string): FolderMember | undefined {
return (entry?.members ?? []).find(member => member.workspaceId === workspaceId)
}
/**
* The remote member for one connection + remote directory, when one exists.
* @param entry - saved folder entry, if any.
* @param profileId - remote-ssh connection id.
* @param remotePath - remote directory to look up.
*/
export function findRemoteMember(entry: WorkspaceFolderEntry | undefined, profileId: string, remotePath: string): FolderMember | undefined {
return (entry?.members ?? []).find(member =>
member.kind === 'remote'
&& member.profileId === profileId
&& member.remotePath !== undefined
&& sameRemotePath(member.remotePath, remotePath))
}
/**
* Every member folder of one owner workspace, in stored order.
* @param doc - folders document.
* @param ownerWorkspaceId - workspace the members hang off.
*/
export function membersOf(doc: FoldersDocument, ownerWorkspaceId: string): readonly FolderMember[] {
return entryFor(doc, ownerWorkspaceId)?.members ?? []
}
/**
* Member workspace id → owning workspace id.
*
* These are the workspaces whose own row disappears from the sidebar: their
* sessions render under the owning project's folder row instead. A workspace
* that is itself an owner (it carries an entry) is never absorbed — absorbing
* it would hide a project together with the folders nested below it.
* @param doc - folders document.
*/
export function absorbedWorkspaceIds(doc: FoldersDocument): ReadonlyMap<string, string> {
const owners = new Set(Object.keys(doc.workspaces))
const absorbed = new Map<string, string>()
for (const [ownerId, entry] of Object.entries(doc.workspaces)) {
for (const member of entry.members ?? []) {
if (member.workspaceId === '' || member.workspaceId === ownerId) continue
if (owners.has(member.workspaceId)) continue
if (!absorbed.has(member.workspaceId)) absorbed.set(member.workspaceId, ownerId)
}
}
return absorbed
}
/**
* True when the entry carries neither a plain folder nor a member, i.e. it can
* be dropped from the sidecar instead of being written empty.
* @param entry - folder entry.
*/
export function isEmptyEntry(entry: WorkspaceFolderEntry | undefined): boolean {
return (entry?.folders.length ?? 0) === 0 && (entry?.members?.length ?? 0) === 0
}
/**
* The folder new sessions start in by default.
* @param workspacePath - canonical directory of the workspace.
* @param entry - saved folder entry, if any.
* @returns the stored root when it names an effective extra folder, else the
* workspace's own directory.
*/
export function rootOf(workspacePath: string, entry: WorkspaceFolderEntry | undefined): string {
const root = entry?.root
if (root === undefined) return workspacePath
const folders = effectiveFolders(workspacePath, entry)
return folders.find(folder => samePath(folder, root)) ?? workspacePath
}
/**
* Owning folder of a session cwd: the most specific (longest) effective folder
* that equals the cwd or is a proper path ancestor of it.
* @param cwd - recorded session cwd; undefined means "the workspace itself".
* @param workspacePath - canonical directory of the workspace.
* @param entry - saved folder entry, if any.
* @returns the owning folder, or the workspace path when nothing matches.
*/
export function folderOfCwd(
cwd: string | undefined,
workspacePath: string,
entry: WorkspaceFolderEntry | undefined,
): string {
if (cwd === undefined) return workspacePath
const target = canonicalPath(cwd)
let best: string | undefined
let bestLength = -1
for (const folder of effectiveFolders(workspacePath, entry)) {
const root = canonicalPath(folder)
if (root === '') continue
const separator = isWindowsStyle(root) ? '\\' : '/'
const prefix = root.endsWith(separator) ? root : `${root}${separator}`
if (target !== root && !target.startsWith(prefix)) continue
if (root.length > bestLength) {
best = folder
bestLength = root.length
}
}
return best ?? workspacePath
}
/**
* Append an extra folder. Idempotent under `samePath`, and the stored root (if
* any) survives untouched.
* @param entry - current entry, or undefined for a workspace with no extras.
* @param path - folder path to append.
*/
export function addFolder(entry: WorkspaceFolderEntry | undefined, path: string): WorkspaceFolderEntry {
const folders = entry?.folders ?? []
const members = entry?.members ?? []
const root = entry?.root
const trimmed = path.trim()
const keepRoot = root === undefined ? {} : { root }
const keepMembers = members.length === 0 ? {} : { members: [...members] }
if (trimmed === '' || folders.some(folder => samePath(folder, trimmed))
|| members.some(member => samePath(member.path, trimmed))) {
return { folders: [...folders], ...keepMembers, ...keepRoot }
}
return { folders: [...folders, trimmed], ...keepMembers, ...keepRoot }
}
/**
* Append a workspace-backed folder. Idempotent under `samePath`: a later call
* for the same path replaces the stored member (so a re-registered workspace id
* wins) instead of stacking a duplicate row.
* @param entry - current entry, or undefined for a workspace with no extras.
* @param member - member record to store.
*/
export function addMember(entry: WorkspaceFolderEntry | undefined, member: FolderMember): WorkspaceFolderEntry {
const folders = (entry?.folders ?? []).filter(folder => !samePath(folder, member.path))
const members = (entry?.members ?? []).filter(existing => !samePath(existing.path, member.path))
const root = entry?.root
// The root survives even when it names the member's own path: the member
// replaces the plain folder at that path, so the root still resolves —
// dropping it would silently change where new sessions start.
const keepRoot = root === undefined ? {} : { root }
return { folders: [...folders], members: [...members, member], ...keepRoot }
}
/**
* Drop an extra folder, plain or workspace-backed. A root that pointed at it is
* cleared, so the workspace falls back to its own directory instead of
* referencing a folder it no longer has.
* @param entry - current entry, or undefined.
* @param path - folder path to drop.
*/
export function removeFolder(entry: WorkspaceFolderEntry | undefined, path: string): WorkspaceFolderEntry {
const folders = (entry?.folders ?? []).filter(folder => !samePath(folder, path))
const members = (entry?.members ?? []).filter(member => !samePath(member.path, path))
const root = entry?.root
const keepRoot = root !== undefined && !samePath(root, path)
const keepMembers = members.length === 0 ? {} : { members }
return { folders: folders, ...keepMembers, ...(keepRoot ? { root } : {}) }
}
/**
* Designate the root folder. Only an extra folder can be stored: naming the
* base directory means "no explicit root", which is represented by clearing
* the key.
* @param entry - current entry, or undefined.
* @param path - folder to make the root.
*/
export function setRoot(entry: WorkspaceFolderEntry | undefined, path: string): WorkspaceFolderEntry {
const folders = entry?.folders ?? []
const members = entry?.members ?? []
const keepMembers = members.length === 0 ? {} : { members: [...members] }
const match = [...folders, ...members.map(member => member.path)]
.find(folder => samePath(folder, path))
if (match === undefined) return { folders: [...folders], ...keepMembers }
return { folders: [...folders], ...keepMembers, root: match }
}
/**
* True when `path` is `base` itself or lives somewhere below it, with the same
* separator and case rules as {@link samePath}.
* @param path - candidate path.
* @param base - containing directory.
*/
export function isUnderBase(path: string, base: string): boolean {
const root = canonicalPath(base)
const target = canonicalPath(path)
if (root === '' || target === '') return false
if (target === root) return true
const separator = isWindowsStyle(root) ? '\\' : '/'
const prefix = root.endsWith(separator) ? root : `${root}${separator}`
return target.startsWith(prefix)
}
/**
* Resolve a user-typed SUBPATH against a base directory.
*
* This is what remote (mirror-backed) workspaces need: their canonical
* directory is a local mirror of a remote root, so an extra folder must be a
* directory INSIDE the mirror — that is the only spelling that also exists on
* the remote side. Absolute input and `..` escapes are rejected outright so a
* typo cannot smuggle in an unrelated local directory.
* @param base - the workspace's canonical directory.
* @param relative - typed subpath, either separator style.
* @returns the joined path, or null when the input is empty, absolute, or
* escapes the base.
*/
export function joinSubpath(base: string, relative: string): string | null {
const root = base.trim()
const raw = relative.trim()
if (root === '' || raw === '') return null
if (WINDOWS_DRIVE.test(raw) || WINDOWS_UNC.test(raw) || raw.startsWith('/')) return null
const segments = raw.split(/[\\/]+/u).filter(segment => segment !== '' && segment !== '.')
if (segments.length === 0) return null
if (segments.includes('..')) return null
const windows = isWindowsStyle(root)
const separator = windows ? '\\' : '/'
return `${withoutTrailingSeparator(root)}${separator}${segments.join(separator)}`
}