@cerbur/clutch-dsh-worktree 0.1.3 → 0.1.4

package/lib/manage/manager-context.d.ts

@@ -0,0 +1,11 @@
+import type { WorktreeManagerOptions } from './types.js';
+import type { GitWorktreeAdapter, SidecarStore } from '../provider/types.js';
+/** Internal Manage composition context shared by the responsibility-specific use-case modules. */
+export interface WorktreeManagerContext {
+    readonly dsh: WorktreeManagerOptions['dsh'];
+    readonly dshHome: string;
+    readonly git: GitWorktreeAdapter;
+    readonly sidecar: SidecarStore;
+    readonly idFactory: () => string;
+}
+//# sourceMappingURL=manager-context.d.ts.map

package/lib/manage/manager-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-context.d.ts","sourceRoot":"","sources":["../../src/manage/manager-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAE7E,kGAAkG;AAClG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAC;CAClC"}

package/lib/manage/manager-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manager-context.js.map

package/lib/manage/manager-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-context.js","sourceRoot":"","sources":["../../src/manage/manager-context.ts"],"names":[],"mappings":""}

package/lib/manage/manager-sessions.d.ts

@@ -0,0 +1,18 @@
+import type { SessionBinding, WorkspaceId } from '../contract/index.js';
+import type { WorktreeManagerContext } from './manager-context.js';
+/** Return active/detached Session relations for one Workspace. */
+export declare function listBindings(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+}): Promise<readonly SessionBinding[]>;
+/** Bind a DSH-created Session whose cwd already targets the Worktree. */
+export declare function bindSession(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+    readonly worktreeId: string;
+    readonly sessionId: string;
+}): Promise<SessionBinding>;
+/** Derive one execution cwd from the current Workspace and binding projection. */
+export declare function resolveRuntimeCwd(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+    readonly sessionId: string;
+}): Promise<string>;
+//# sourceMappingURL=manager-sessions.d.ts.map

package/lib/manage/manager-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-sessions.d.ts","sourceRoot":"","sources":["../../src/manage/manager-sessions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAGnE,kEAAkE;AAClE,wBAAsB,YAAY,CAChC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;CAAE,GAC3C,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAGpC;AAED,yEAAyE;AACzE,wBAAsB,WAAW,CAC/B,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpG,OAAO,CAAC,cAAc,CAAC,CAoDzB;AAED,kFAAkF;AAClF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvE,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/lib/manage/manager-sessions.js

@@ -0,0 +1,91 @@
+import { providerError } from '../provider/types.js';
+import { assertSessionMatchesWorkspace, isDirectory, requireWorkspace } from './manager-support.js';
+/** Return active/detached Session relations for one Workspace. */
+export async function listBindings(context, input) {
+    await requireWorkspace(context, input.workspaceId);
+    return (await context.sidecar.read(input.workspaceId)).bindings;
+}
+/** Bind a DSH-created Session whose cwd already targets the Worktree. */
+export async function bindSession(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    // Duplicate checks, DSH fact validation, and append happen in one serialized mutation.
+    return context.sidecar.mutate(input.workspaceId, async (snapshot) => {
+        const worktree = snapshot.worktrees.find((candidate) => candidate.worktreeId === input.worktreeId);
+        if (!worktree) {
+            throw providerError('WORKTREE_NOT_FOUND', `Worktree not found: ${input.worktreeId}`, {
+                workspaceId: input.workspaceId,
+                worktreeId: input.worktreeId,
+            });
+        }
+        if (worktree.status === 'removed') {
+            throw providerError('WORKTREE_REMOVED', `Worktree has been removed: ${input.worktreeId}`, {
+                workspaceId: input.workspaceId,
+                worktreeId: input.worktreeId,
+            });
+        }
+        const existing = snapshot.bindings.find((binding) => binding.sessionId === input.sessionId);
+        if (existing) {
+            if (existing.worktreeId === input.worktreeId && existing.status === 'active') {
+                // Exact retries do not write; detached history is never implicitly reactivated.
+                return { result: existing, snapshot, changed: false };
+            }
+            throw providerError('SESSION_ALREADY_BOUND', `Session is already bound to Worktree ${existing.worktreeId}`, {
+                sessionId: input.sessionId,
+                worktreeId: existing.worktreeId,
+            });
+        }
+        // Session identity, Workspace ownership, and cwd come from DSH; validation never writes corrections back.
+        const session = await context.dsh.getSession(input.sessionId);
+        if (!session) {
+            throw providerError('SESSION_NOT_FOUND', `Session not found: ${input.sessionId}`, {
+                sessionId: input.sessionId,
+            });
+        }
+        assertSessionMatchesWorkspace(session, workspace, worktree);
+        const binding = {
+            workspaceId: input.workspaceId,
+            worktreeId: input.worktreeId,
+            sessionId: input.sessionId,
+            status: 'active',
+        };
+        return {
+            result: binding,
+            // Worktree Session groups render bindings in sidecar order; prepend the newly created Session.
+            snapshot: { ...snapshot, bindings: [binding, ...snapshot.bindings] },
+        };
+    });
+}
+/** Derive one execution cwd from the current Workspace and binding projection. */
+export async function resolveRuntimeCwd(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    const snapshot = await context.sidecar.read(input.workspaceId);
+    const binding = snapshot.bindings.find((candidate) => candidate.sessionId === input.sessionId);
+    // Detached is a safe main fallback; a broken active relation fails explicitly below.
+    if (!binding || binding.status === 'detached')
+        return workspace.rootPath;
+    const worktree = snapshot.worktrees.find((candidate) => candidate.worktreeId === binding.worktreeId);
+    if (!worktree) {
+        throw providerError('WORKTREE_NOT_FOUND', `Active binding points to a missing Worktree: ${binding.worktreeId}`, {
+            workspaceId: input.workspaceId,
+            worktreeId: binding.worktreeId,
+            sessionId: input.sessionId,
+        });
+    }
+    if (worktree.status !== 'active') {
+        throw providerError('WORKTREE_REMOVED', `Active binding points to a removed Worktree: ${worktree.worktreeId}`, {
+            workspaceId: input.workspaceId,
+            worktreeId: worktree.worktreeId,
+            sessionId: input.sessionId,
+        });
+    }
+    if (!(await isDirectory(worktree.absolutePath))) {
+        throw providerError('WORKTREE_NOT_FOUND', `Active Worktree path does not exist: ${worktree.absolutePath}`, {
+            workspaceId: input.workspaceId,
+            worktreeId: worktree.worktreeId,
+            sessionId: input.sessionId,
+            absolutePath: worktree.absolutePath,
+        });
+    }
+    return worktree.absolutePath;
+}
+//# sourceMappingURL=manager-sessions.js.map

package/lib/manage/manager-sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-sessions.js","sourceRoot":"","sources":["../../src/manage/manager-sessions.ts"],"names":[],"mappings":"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"}

package/lib/manage/manager-support.d.ts

@@ -0,0 +1,18 @@
+import type { WorktreeRecord } from '../contract/index.js';
+import { type DshSessionSummary, type DshWorkspaceSummary, type SidecarSnapshot, WorktreeProviderError } from '../provider/types.js';
+import type { WorktreeManagerContext } from './manager-context.js';
+export declare function isSameOrInside(parent: string, candidate: string): boolean;
+export declare function isDirectory(filePath: string): Promise<boolean>;
+export declare function pathExists(filePath: string): Promise<boolean>;
+export declare function samePhysicalPath(left: string, right: string): Promise<boolean>;
+export declare function rejectSymlink(filePath: string, label: string): Promise<void>;
+export declare function asGitError(operation: string, workspaceRoot: string, targetPath: string | undefined, error: unknown): WorktreeProviderError;
+export declare function asSidecarError(error: unknown, workspaceId: string): WorktreeProviderError;
+export declare function describeError(error: unknown): string;
+export declare function generatedId(idFactory: () => string): string;
+export declare function requireWorkspace(context: WorktreeManagerContext, workspaceId: string): Promise<DshWorkspaceSummary>;
+export declare function validateGeneratedPath(context: WorktreeManagerContext, workspaceRoot: string, targetPath: string, worktreeId: string): void;
+export declare function validatePhysicalGeneratedPath(context: WorktreeManagerContext, workspaceRoot: string, targetPath: string): Promise<void>;
+export declare function assertSessionMatchesWorkspace(session: DshSessionSummary, workspace: DshWorkspaceSummary, worktree: WorktreeRecord): void;
+export type { SidecarSnapshot };
+//# sourceMappingURL=manager-support.d.ts.map

package/lib/manage/manager-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-support.d.ts","sourceRoot":"","sources":["../../src/manage/manager-support.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,qBAAqB,EAGtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAInE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGzE;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOpE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQnE;AAID,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMpF;AAID,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAelF;AAED,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,KAAK,EAAE,OAAO,GACb,qBAAqB,CAOvB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,qBAAqB,CAMzF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,MAAM,GAAG,MAAM,CAM3D;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,sBAAsB,EAC/B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAyB9B;AAID,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CASN;AAID,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,sBAAsB,EAC/B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAwBf;AAID,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,cAAc,GACvB,IAAI,CAkBN;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/lib/manage/manager-support.js

@@ -0,0 +1,174 @@
+import { lstat, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { isWorktreeProviderError, providerError, } from '../provider/types.js';
+// 这是词法边界检查，既接受 parent 本身也接受其后代；物理路径边界会在后续单独校验。
+// This is a lexical boundary check that accepts parent itself and descendants; physical boundaries are validated separately later.
+export function isSameOrInside(parent, candidate) {
+    const relative = path.relative(parent, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+export async function isDirectory(filePath) {
+    try {
+        return (await stat(filePath)).isDirectory();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+// 优先比较 canonical path 以覆盖符号链接/路径别名；无法 canonicalize 时退回绝对词法比较。
+// Prefer canonical paths to cover symlinks and aliases; fall back to absolute lexical comparison when canonicalization is unavailable.
+export async function samePhysicalPath(left, right) {
+    try {
+        return (await realpath(left)) === (await realpath(right));
+    }
+    catch {
+        return path.resolve(left) === path.resolve(right);
+    }
+}
+// 已存在的受信边界不允许是 symlink，避免后续创建绕过 DSH Home 的物理目录约束。
+// Existing trusted boundaries may not be symlinks, preventing later creation from escaping the physical DSH Home boundary.
+export async function rejectSymlink(filePath, label) {
+    try {
+        if ((await lstat(filePath)).isSymbolicLink()) {
+            throw providerError('GIT_OPERATION_FAILED', `${label} must not be a symlink: ${filePath}`, {
+                path: filePath,
+            });
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        if (isWorktreeProviderError(error))
+            throw error;
+        throw providerError('GIT_OPERATION_FAILED', `Unable to inspect ${label}: ${filePath}`, {
+            path: filePath,
+            cause: String(error),
+        });
+    }
+}
+export function asGitError(operation, workspaceRoot, targetPath, error) {
+    if (isWorktreeProviderError(error))
+        return error;
+    return providerError('GIT_OPERATION_FAILED', `Git ${operation} failed: ${String(error)}`, {
+        workspaceRoot,
+        ...(targetPath ? { targetPath } : {}),
+        operation,
+    });
+}
+export function asSidecarError(error, workspaceId) {
+    if (isWorktreeProviderError(error))
+        return error;
+    return providerError('SIDECAR_UNAVAILABLE', `Sidecar operation failed for Workspace ${workspaceId}`, {
+        workspaceId,
+        cause: String(error),
+    });
+}
+export function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function generatedId(idFactory) {
+    const worktreeId = idFactory();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(worktreeId)) {
+        throw providerError('GIT_OPERATION_FAILED', 'Provider generated an invalid Worktree ID', { worktreeId });
+    }
+    return worktreeId;
+}
+export async function requireWorkspace(context, workspaceId) {
+    const workspace = await context.dsh.getWorkspace(workspaceId);
+    if (!workspace || workspace.workspaceId !== workspaceId || !path.isAbsolute(workspace.rootPath)) {
+        throw providerError('WORKSPACE_NOT_FOUND', `Workspace is missing or has a non-absolute root: ${workspaceId}`, {
+            workspaceId,
+            rootPath: workspace?.rootPath ?? '',
+        });
+    }
+    const rootPath = path.resolve(workspace.rootPath);
+    if (!(await isDirectory(rootPath))) {
+        throw providerError('WORKSPACE_NOT_FOUND', `Workspace root does not exist: ${rootPath}`, {
+            workspaceId,
+            rootPath,
+        });
+    }
+    try {
+        await realpath(rootPath);
+    }
+    catch (error) {
+        throw providerError('WORKSPACE_NOT_FOUND', `Unable to resolve Workspace root: ${rootPath}`, {
+            workspaceId,
+            rootPath,
+            cause: String(error),
+        });
+    }
+    return { ...workspace, rootPath };
+}
+// 第一层使用未解析路径验证目标属于插件根且不位于 Workspace 内。
+// The first layer uses unresolved paths to ensure the target belongs to the plugin root and is not inside the Workspace.
+export function validateGeneratedPath(context, workspaceRoot, targetPath, worktreeId) {
+    const pluginRoot = path.resolve(context.dshHome, 'clutch-dsh-worktree');
+    if (!isSameOrInside(pluginRoot, targetPath) || isSameOrInside(workspaceRoot, targetPath)) {
+        throw providerError('GIT_OPERATION_FAILED', 'Generated Worktree path is outside the allowed boundary', {
+            workspaceRoot,
+            targetPath,
+            worktreeId,
+        });
+    }
+}
+// 第二层拒绝受信祖先 symlink，并以 realpath 后的根重新计算目标，防止物理路径逃逸。
+// The second layer rejects symlinked trusted ancestors and recomputes the target from the realpath root to prevent physical path escape.
+export async function validatePhysicalGeneratedPath(context, workspaceRoot, targetPath) {
+    await rejectSymlink(context.dshHome, 'DSH Home');
+    await rejectSymlink(path.join(context.dshHome, 'clutch-dsh-worktree'), 'plugin sidecar root');
+    await rejectSymlink(path.join(context.dshHome, 'clutch-dsh-worktree', 'worktree'), 'Worktree root');
+    let canonicalDshHome;
+    try {
+        canonicalDshHome = await realpath(context.dshHome);
+    }
+    catch (error) {
+        throw providerError('SIDECAR_UNAVAILABLE', `Unable to resolve DSH Home: ${context.dshHome}`, {
+            dshHome: context.dshHome,
+            cause: String(error),
+        });
+    }
+    const targetRelativeToDshHome = path.relative(context.dshHome, targetPath);
+    const canonicalTarget = path.resolve(canonicalDshHome, targetRelativeToDshHome);
+    const canonicalWorkspace = await realpath(workspaceRoot);
+    if (!isSameOrInside(canonicalDshHome, canonicalTarget) || isSameOrInside(canonicalWorkspace, canonicalTarget)) {
+        throw providerError('GIT_OPERATION_FAILED', 'Generated Worktree path crosses a physical boundary', {
+            workspaceRoot: canonicalWorkspace,
+            dshHome: canonicalDshHome,
+            targetPath: canonicalTarget,
+        });
+    }
+}
+// 绑定只接受 DSH 已按目标 Worktree cwd 创建的 Session；Manager 不替用户迁移或改写 Session。
+// Binding accepts only Sessions already created by DSH with the target Worktree cwd; the Manager never migrates or rewrites a Session.
+export function assertSessionMatchesWorkspace(session, workspace, worktree) {
+    if ((session.workspaceId !== undefined && session.workspaceId !== workspace.workspaceId) ||
+        (session.projectId !== undefined &&
+            workspace.projectId !== undefined &&
+            session.projectId !== workspace.projectId) ||
+        !path.isAbsolute(session.cwd) ||
+        path.resolve(session.cwd) !== path.resolve(worktree.absolutePath)) {
+        throw providerError('SESSION_CWD_MISMATCH', `Session cwd or Workspace association does not match Worktree`, {
+            sessionId: session.sessionId,
+            workspaceId: workspace.workspaceId,
+            expectedCwd: worktree.absolutePath,
+            actualCwd: session.cwd,
+            sessionWorkspaceId: session.workspaceId ?? '',
+            sessionProjectId: session.projectId ?? '',
+        });
+    }
+}
+//# sourceMappingURL=manager-support.js.map

package/lib/manage/manager-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-support.js","sourceRoot":"","sources":["../../src/manage/manager-support.ts"],"names":[],"mappings":"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"}

package/lib/manage/manager-worktrees.d.ts

@@ -0,0 +1,27 @@
+import type { BranchRecord, WorktreeId, WorktreeRecord, WorkspaceId } from '../contract/index.js';
+import type { WorktreeManagerContext } from './manager-context.js';
+/** Return the sidecar Worktree projection with runtime Git health attached. */
+export declare function listWorktrees(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+}): Promise<readonly WorktreeRecord[]>;
+/** Project local branches against all Git worktrees and mark checkout/current state. */
+export declare function listBranches(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+}): Promise<readonly BranchRecord[]>;
+/** Create a Git Worktree first, then commit its external relation to the sidecar. */
+export declare function createWorktree(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+    readonly branch: string;
+    readonly newBranch?: string;
+}): Promise<WorktreeRecord>;
+/** Remove Git state first, then mark the relation removed while preserving detached bindings. */
+export declare function removeWorktree(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+    readonly worktreeId: string;
+}): Promise<void>;
+export declare function insertWorktreeBefore(context: WorktreeManagerContext, input: {
+    readonly workspaceId: WorkspaceId;
+    readonly worktreeId: WorktreeId;
+    readonly beforeWorktreeId?: WorktreeId;
+}): Promise<readonly WorktreeId[]>;
+//# sourceMappingURL=manager-worktrees.d.ts.map

package/lib/manage/manager-worktrees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager-worktrees.d.ts","sourceRoot":"","sources":["../../src/manage/manager-worktrees.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAElG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAanE,+EAA+E;AAC/E,wBAAsB,aAAa,CACjC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;CAAE,GAC3C,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAoCpC;AAED,wFAAwF;AACxF,wBAAsB,YAAY,CAChC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;CAAE,GAC3C,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAsBlC;AAED,qFAAqF;AACrF,wBAAsB,cAAc,CAClC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACjG,OAAO,CAAC,cAAc,CAAC,CAqIzB;AAED,iGAAiG;AACjG,wBAAsB,cAAc,CAClC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxE,OAAO,CAAC,IAAI,CAAC,CAuEf;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,sBAAsB,EAC/B,KAAK,EAAE;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAA;CAAE,GACpH,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAWhC"}

package/lib/manage/manager-worktrees.js

@@ -0,0 +1,259 @@
+import path from 'node:path';
+import { providerError } from '../provider/types.js';
+import { asGitError, asSidecarError, describeError, generatedId, pathExists, requireWorkspace, samePhysicalPath, validateGeneratedPath, validatePhysicalGeneratedPath, } from './manager-support.js';
+/** Return the sidecar Worktree projection with runtime Git health attached. */
+export async function listWorktrees(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    const records = (await context.sidecar.read(input.workspaceId)).worktrees;
+    let gitWorktrees;
+    try {
+        gitWorktrees = await context.git.listWorktrees(workspace.rootPath);
+    }
+    catch {
+        return records.map((record) => {
+            const { health: _health, ...durableRecord } = record;
+            void _health;
+            return record.status === 'active'
+                ? { ...durableRecord, health: 'repair' }
+                : durableRecord;
+        });
+    }
+    const nextRecords = [];
+    for (const record of records) {
+        const { health: _health, ...durableRecord } = record;
+        void _health;
+        if (record.status !== 'active') {
+            nextRecords.push(durableRecord);
+            continue;
+        }
+        let ready = false;
+        for (const gitWorktree of gitWorktrees) {
+            if (path.resolve(gitWorktree.absolutePath) === path.resolve(record.absolutePath) ||
+                (await samePhysicalPath(gitWorktree.absolutePath, record.absolutePath))) {
+                ready = true;
+                break;
+            }
+        }
+        nextRecords.push({ ...durableRecord, health: ready ? 'ready' : 'repair' });
+    }
+    return nextRecords;
+}
+/** Project local branches against all Git worktrees and mark checkout/current state. */
+export async function listBranches(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    await context.git.validateRepository(workspace.rootPath);
+    const [branches, worktrees] = await Promise.all([
+        context.git.listBranches(workspace.rootPath),
+        context.git.listWorktrees(workspace.rootPath),
+    ]);
+    // `checkedOut` covers the main Workspace and all linked worktree; `isCurrent` only identifies the entry at the Workspace root's physical path.
+    const checkedOut = new Set(worktrees.flatMap((worktree) => (worktree.branch ? [worktree.branch] : [])));
+    let currentBranch;
+    for (const worktree of worktrees) {
+        if (await samePhysicalPath(worktree.absolutePath, workspace.rootPath)) {
+            currentBranch = worktree.branch;
+            break;
+        }
+    }
+    return branches.map((name) => ({
+        name,
+        isCurrent: currentBranch === name,
+        checkedOut: checkedOut.has(name),
+    }));
+}
+/** Create a Git Worktree first, then commit its external relation to the sidecar. */
+export async function createWorktree(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    await context.git.validateRepository(workspace.rootPath);
+    if (typeof input.branch !== 'string' || input.branch.length === 0) {
+        throw providerError('GIT_OPERATION_FAILED', 'A local branch is required', {
+            workspaceRoot: workspace.rootPath,
+        });
+    }
+    const baseBranch = input.branch.trim();
+    if (input.newBranch !== undefined && typeof input.newBranch !== 'string') {
+        throw providerError('GIT_OPERATION_FAILED', 'A new branch name must be a string', {
+            workspaceRoot: workspace.rootPath,
+            baseBranch,
+        });
+    }
+    const newBranch = input.newBranch?.trim();
+    if (baseBranch.length === 0) {
+        throw providerError('GIT_OPERATION_FAILED', 'A local base branch is required', {
+            workspaceRoot: workspace.rootPath,
+        });
+    }
+    if (input.newBranch !== undefined && (!newBranch || newBranch === baseBranch)) {
+        throw providerError('GIT_OPERATION_FAILED', 'A distinct new branch name is required', {
+            workspaceRoot: workspace.rootPath,
+            baseBranch,
+            newBranch: input.newBranch,
+        });
+    }
+    const branches = await context.git.listBranches(workspace.rootPath);
+    if (!branches.includes(baseBranch)) {
+        throw providerError('GIT_OPERATION_FAILED', `Local branch does not exist: ${baseBranch}`, {
+            workspaceRoot: workspace.rootPath,
+            branch: baseBranch,
+        });
+    }
+    const targetBranch = newBranch ?? baseBranch;
+    if (newBranch !== undefined && branches.includes(newBranch)) {
+        throw providerError('WORKTREE_BRANCH_CONFLICT', `New branch already exists: ${newBranch}`, {
+            workspaceRoot: workspace.rootPath,
+            branch: newBranch,
+            baseBranch,
+        });
+    }
+    const existingGitWorktrees = await context.git.listWorktrees(workspace.rootPath);
+    if (existingGitWorktrees.some((worktree) => worktree.branch === targetBranch)) {
+        throw providerError('WORKTREE_BRANCH_CONFLICT', `Branch is already checked out: ${targetBranch}`, {
+            workspaceRoot: workspace.rootPath,
+            branch: targetBranch,
+            baseBranch,
+        });
+    }
+    const worktreeId = generatedId(context.idFactory);
+    const targetPath = path.resolve(context.dshHome, 'clutch-dsh-worktree', 'worktree', worktreeId);
+    // 创建前同时检查词法和物理目录边界，阻止配置、ID 或 symlink 将目标引回 Workspace 或带出插件根目录。
+    // Check lexical and physical directory boundaries before creation so configuration, IDs, or symlinks cannot redirect the target into the Workspace or outside the plugin root.
+    validateGeneratedPath(context, workspace.rootPath, targetPath, worktreeId);
+    await validatePhysicalGeneratedPath(context, workspace.rootPath, targetPath);
+    if (await pathExists(targetPath)) {
+        throw providerError('GIT_OPERATION_FAILED', `Generated Worktree path already exists: ${targetPath}`, {
+            workspaceRoot: workspace.rootPath,
+            targetPath,
+            worktreeId,
+        });
+    }
+    // Git is the first external side effect; the sidecar mutation below is the relation commit point.
+    try {
+        await context.git.createWorktree(workspace.rootPath, targetPath, baseBranch, newBranch);
+    }
+    catch (error) {
+        throw asGitError('create worktree', workspace.rootPath, targetPath, error);
+    }
+    const record = {
+        worktreeId,
+        workspaceId: input.workspaceId,
+        absolutePath: targetPath,
+        branch: targetBranch,
+        status: 'active',
+    };
+    try {
+        return await context.sidecar.mutate(input.workspaceId, (snapshot) => {
+            // Recheck ID and branch inside the serialized mutation so concurrent writes cannot create duplicate active records.
+            const idConflict = snapshot.worktrees.find((worktree) => worktree.worktreeId === worktreeId);
+            if (idConflict) {
+                throw providerError('SIDECAR_CORRUPT', `Generated Worktree ID is already recorded: ${worktreeId}`, {
+                    worktreeId,
+                    existingStatus: idConflict.status,
+                });
+            }
+            const branchConflict = snapshot.worktrees.find((worktree) => worktree.status === 'active' && worktree.branch === targetBranch);
+            if (branchConflict) {
+                throw providerError('WORKTREE_BRANCH_CONFLICT', `Branch is already recorded as active: ${targetBranch}`, {
+                    branch: targetBranch,
+                    worktreeId: branchConflict.worktreeId,
+                });
+            }
+            const next = {
+                ...snapshot,
+                worktrees: [...snapshot.worktrees, record],
+            };
+            return { result: record, snapshot: next };
+        });
+    }
+    catch (error) {
+        const sidecarError = asSidecarError(error, input.workspaceId);
+        // Remove the new Worktree when sidecar commit fails; expose a sync-required error if compensation fails.
+        try {
+            await context.git.removeWorktree(workspace.rootPath, targetPath);
+        }
+        catch (cleanupError) {
+            throw providerError('SIDECAR_SYNC_REQUIRED', `Sidecar write failed and the newly created Worktree could not be cleaned up: ${targetPath}`, {
+                workspaceId: input.workspaceId,
+                workspaceRoot: workspace.rootPath,
+                targetPath,
+                sidecarError: sidecarError.message,
+                cleanupError: describeError(cleanupError),
+            });
+        }
+        throw sidecarError;
+    }
+}
+/** Remove Git state first, then mark the relation removed while preserving detached bindings. */
+export async function removeWorktree(context, input) {
+    const workspace = await requireWorkspace(context, input.workspaceId);
+    let gitRemoved = false;
+    try {
+        await context.sidecar.mutate(input.workspaceId, async (snapshot) => {
+            const record = snapshot.worktrees.find((worktree) => worktree.worktreeId === input.worktreeId);
+            if (!record) {
+                throw providerError('WORKTREE_NOT_FOUND', `Worktree not found: ${input.worktreeId}`, {
+                    worktreeId: input.worktreeId,
+                    workspaceId: input.workspaceId,
+                });
+            }
+            if (record.status === 'removed') {
+                throw providerError('WORKTREE_REMOVED', `Worktree has already been removed: ${input.worktreeId}`, {
+                    worktreeId: input.worktreeId,
+                });
+            }
+            try {
+                await context.git.removeWorktree(workspace.rootPath, record.absolutePath);
+            }
+            catch (error) {
+                let stillRegistered;
+                try {
+                    stillRegistered = false;
+                    for (const worktree of await context.git.listWorktrees(workspace.rootPath)) {
+                        if (await samePhysicalPath(worktree.absolutePath, record.absolutePath)) {
+                            stillRegistered = true;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    throw asGitError('remove worktree', workspace.rootPath, record.absolutePath, error);
+                }
+                if (stillRegistered) {
+                    throw asGitError('remove worktree', workspace.rootPath, record.absolutePath, error);
+                }
+            }
+            gitRemoved = true;
+            // Preserve Worktree and binding history while changing lifecycle only; DSH Sessions are never read or deleted here.
+            const next = {
+                ...snapshot,
+                worktrees: snapshot.worktrees.map((candidate) => candidate.worktreeId === record.worktreeId ? { ...candidate, status: 'removed' } : candidate),
+                bindings: snapshot.bindings.map((binding) => binding.worktreeId === record.worktreeId && binding.status === 'active'
+                    ? { ...binding, status: 'detached' }
+                    : binding),
+            };
+            return { result: undefined, snapshot: next };
+        });
+    }
+    catch (error) {
+        if (gitRemoved) {
+            // Git removal cannot be rolled back here, so expose the divergence for a safe retry.
+            const sidecarError = asSidecarError(error, input.workspaceId);
+            throw providerError('SIDECAR_SYNC_REQUIRED', `Git removed Worktree ${input.worktreeId}, but sidecar synchronization failed`, {
+                workspaceId: input.workspaceId,
+                worktreeId: input.worktreeId,
+                workspaceRoot: workspace.rootPath,
+                sidecarError: sidecarError.message,
+            });
+        }
+        throw error;
+    }
+}
+export async function insertWorktreeBefore(context, input) {
+    await requireWorkspace(context, input.workspaceId);
+    try {
+        return await context.sidecar.insertWorktreeBefore(input.workspaceId, input.worktreeId, input.beforeWorktreeId);
+    }
+    catch (error) {
+        throw asSidecarError(error, input.workspaceId);
+    }
+}
+//# sourceMappingURL=manager-worktrees.js.map