@cerbur/clutch-dsh-worktree 0.1.2 → 0.1.4

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

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

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

package/lib/manage/manager.d.ts

@@ -1,86 +1,49 @@
-import type { BranchRecord, SessionBinding, WorktreeRecord, WorkspaceId } from '../contract/index.js';
+import type { BranchRecord, SessionBinding, WorktreeId, WorktreeRecord, WorkspaceId } from '../contract/index.js';
 import type { WorktreeManagerOptions, WorktreeManagerService } from './types.js';
 /**
  * Worktree/Session 用例编排器：DSH 只提供权威只读事实，Git 承担 worktree 副作用，sidecar 只保存外部关系。
  * Worktree/Session use-case orchestrator: DSH supplies authoritative read-only facts, Git owns worktree side effects, and the sidecar stores only external relations.
+ *
+ * The public Manager contract stays here while the worktree and Session
+ * workflows live in responsibility-specific internal modules.
  */
 export declare class WorktreeManagerImpl implements WorktreeManagerService {
-    private readonly dsh;
-    private readonly dshHome;
-    private readonly git;
-    private readonly sidecar;
-    private readonly idFactory;
-    /**
-     * 使用可注入端口组合 Manager；未注入的 Git 与 sidecar 端口会绑定到本地 Provider 实现。
-     * Composes the Manager from injectable ports; omitted Git and sidecar ports bind to local Provider implementations.
-     */
+    private readonly context;
+    /** Compose the Manager from injectable ports while keeping local defaults. */
     constructor(options: WorktreeManagerOptions);
-    /**
-     * 返回含 active/removed 状态的 sidecar Worktree 投影。
-     * Returns the sidecar Worktree projection, including active/removed state.
-     */
     listWorktrees(input: {
-        workspaceId: WorkspaceId;
+        readonly workspaceId: WorkspaceId;
     }): Promise<readonly WorktreeRecord[]>;
-    /**
-     * 将本地分支与所有 Git worktree 联合投影，以便调用方禁用已 checkout 的分支。
-     * Projects local branches against every Git worktree so callers can disable branches that are already checked out.
-     */
     listBranches(input: {
-        workspaceId: WorkspaceId;
+        readonly workspaceId: WorkspaceId;
     }): Promise<readonly BranchRecord[]>;
-    /**
-     * 创建受 DSH Home 边界管理的 Git Worktree，并仅在 sidecar 提交成功后返回；已 checkout 的
-     * base branch 可以通过 newBranch 创建新的本地 branch。持久化失败会补偿删除 Git Worktree。
-     * Creates a Git Worktree inside the managed DSH Home boundary and returns only after sidecar
-     * commit. An already checked-out base branch can create a new local branch through newBranch.
-     * Persistence failure compensates by removing the Git Worktree.
-     */
     createWorktree(input: {
-        workspaceId: WorkspaceId;
-        branch: string;
-        newBranch?: string;
+        readonly workspaceId: WorkspaceId;
+        readonly branch: string;
+        readonly newBranch?: string;
     }): Promise<WorktreeRecord>;
-    /**
-     * 先删除 Git Worktree，再原子标记 record 为 removed 并保留 detached bindings；失败阶段决定该操作是否可直接重试或需要同步修复。
-     * Removes the Git Worktree first, then atomically marks its record removed and preserves detached bindings; the failure phase determines whether retry or synchronization repair is required.
-     */
     removeWorktree(input: {
-        workspaceId: WorkspaceId;
-        worktreeId: string;
+        readonly workspaceId: WorkspaceId;
+        readonly worktreeId: string;
     }): Promise<void>;
-    /**
-     * 返回 Workspace 的 active/detached Session 关系。
-     * Returns active/detached Session relations for the Workspace.
-     */
+    insertWorktreeBefore(input: {
+        readonly workspaceId: WorkspaceId;
+        readonly worktreeId: WorktreeId;
+        readonly beforeWorktreeId?: WorktreeId;
+    }): Promise<readonly WorktreeId[]>;
     listBindings(input: {
-        workspaceId: WorkspaceId;
+        readonly workspaceId: WorkspaceId;
     }): Promise<readonly SessionBinding[]>;
-    /**
-     * 将已由 DSH 创建且 cwd 指向目标 Worktree 的 Session 绑定到 sidecar；相同 active 请求幂等，其他既有关系一律冲突。
-     * Binds a DSH-created Session whose cwd already targets the Worktree; the same active request is idempotent and every other existing relation conflicts.
-     */
     bindSession(input: {
-        workspaceId: WorkspaceId;
-        worktreeId: string;
-        sessionId: string;
+        readonly workspaceId: WorkspaceId;
+        readonly worktreeId: string;
+        readonly sessionId: string;
     }): Promise<SessionBinding>;
-    /**
-     * 派生一次执行的 cwd：无 binding 或 detached 时使用 Workspace root，active 时要求对应 Worktree 记录和目录均有效。
-     * Derives cwd for one execution: no binding or detached uses the Workspace root, while active requires both a valid Worktree record and directory.
-     */
     resolveRuntimeCwd(input: {
-        workspaceId: WorkspaceId;
-        sessionId: string;
+        readonly workspaceId: WorkspaceId;
+        readonly sessionId: string;
     }): Promise<string>;
-    private requireWorkspace;
-    private validateGeneratedPath;
-    private validatePhysicalGeneratedPath;
-    private assertSessionMatchesWorkspace;
 }
-/**
- * 创建实现 `WorktreeManagerService` 的默认编排器，同时保留所有底层端口的注入能力。
- * Creates the default `WorktreeManagerService` orchestrator while preserving injection for every low-level port.
- */
+/** Create the default WorktreeManagerService while preserving low-level port injection. */
 export declare function createWorktreeManager(options: WorktreeManagerOptions): WorktreeManagerService;
 //# sourceMappingURL=manager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/manage/manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,cAAc,EACd,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAc9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AA2FjF;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,sBAAsB;IAChE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgC;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;OAGG;gBACS,OAAO,EAAE,sBAAsB;IAa3C;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAsC5F;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAyBzF;;;;;;OAMG;IACG,cAAc,CAAC,KAAK,EAAE;QAC1B,WAAW,EAAE,WAAW,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,cAAc,CAAC;IA0I3B;;;OAGG;IACG,cAAc,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,WAAW,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgF5F;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAK3F;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE;QACvB,WAAW,EAAE,WAAW,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,cAAc,CAAC;IAwD3B;;;OAGG;IACG,iBAAiB,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,WAAW,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YAqClF,gBAAgB;IA6B9B,OAAO,CAAC,qBAAqB;YAaf,6BAA6B;IA4B3C,OAAO,CAAC,6BAA6B;CAuBtC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAE7F"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/manage/manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAiBlH,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEjF;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,sBAAsB;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD,8EAA8E;gBAClE,OAAO,EAAE,sBAAsB;IAgB3C,aAAa,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAI/F,YAAY,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC;IAI5F,cAAc,CAAC,KAAK,EAAE;QACpB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3B,cAAc,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxG,oBAAoB,CAAC,KAAK,EAAE;QAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAClC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;QAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAC;KACxC,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAIlC,YAAY,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAI9F,WAAW,CAAC,KAAK,EAAE;QACjB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,GAAG,OAAO,CAAC,cAAc,CAAC;IAI3B,iBAAiB,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;CAG7G;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAE7F"}