git-workspace-service 0.1.0 → 0.3.0

package/README.md

@@ -5,6 +5,7 @@ Git workspace provisioning and credential management service. Handles cloning re
 ## Features
 
 - **Workspace provisioning** - Clone repos, create branches, configure git
+- **Git Worktrees** - Fast parallel workspaces with shared .git directory
 - **Credential management** - Secure credential handling with TTL and revocation
 - **Multiple providers** - Support for GitHub, GitLab, Bitbucket, Azure DevOps
 - **GitHub App support** - First-class GitHub App authentication
@@ -213,6 +214,73 @@ const permissions = {
 };
 ```
 
+## Git Worktrees
+
+For parallel work on the same repository, use worktrees instead of clones. Worktrees share the `.git` directory, making them faster to create and using less disk space.
+
+```
+┌──────────────────────────┬────────────────────────────────────────┐
+│          Clone           │                Worktree                │
+├──────────────────────────┼────────────────────────────────────────┤
+│ Full .git copy each time │ Shared .git directory                  │
+│ Slower for same repo     │ Fast - just checkout                   │
+│ More disk space          │ Minimal disk                           │
+│ Good for different repos │ Perfect for parallel work on SAME repo │
+└──────────────────────────┴────────────────────────────────────────┘
+```
+
+### Creating a Worktree
+
+```typescript
+// First, create a clone workspace (the parent)
+const parent = await workspaceService.provision({
+  repo: 'https://github.com/owner/repo',
+  strategy: 'clone',  // explicit, but this is the default
+  branchStrategy: 'feature_branch',
+  baseBranch: 'main',
+  execution: { id: 'exec-123', patternName: 'review' },
+  task: { id: 'task-1', role: 'architect' },
+});
+
+// Then create worktrees from it for parallel agents
+const reviewerWorkspace = await workspaceService.provision({
+  repo: 'https://github.com/owner/repo',
+  strategy: 'worktree',
+  parentWorkspace: parent.id,  // Required for worktrees
+  branchStrategy: 'feature_branch',
+  baseBranch: 'main',
+  execution: { id: 'exec-123', patternName: 'review' },
+  task: { id: 'task-2', role: 'reviewer' },
+});
+
+// Or use the convenience method
+const testerWorkspace = await workspaceService.addWorktree(parent.id, {
+  branch: 'main',
+  execution: { id: 'exec-123', patternName: 'review' },
+  task: { id: 'task-3', role: 'tester' },
+});
+```
+
+### Managing Worktrees
+
+```typescript
+// List all worktrees for a parent
+const worktrees = workspaceService.listWorktrees(parent.id);
+
+// Remove a specific worktree
+await workspaceService.removeWorktree(reviewerWorkspace.id);
+
+// Cleanup parent also cleans up all its worktrees
+await workspaceService.cleanup(parent.id);
+```
+
+### Worktree Benefits for Multi-Agent Systems
+
+- **Shared credentials**: Worktrees reuse the parent's credential
+- **Faster provisioning**: No network clone, just local checkout
+- **Less disk space**: Single .git directory shared across all worktrees
+- **Isolated branches**: Each worktree can work on a different branch
+
 ## Event System
 
 Subscribe to workspace lifecycle events:
@@ -406,6 +474,8 @@ class FileTokenStore extends TokenStore {
 | `workspace:error` | Workspace provisioning failed |
 | `workspace:finalizing` | Workspace finalization started |
 | `workspace:cleaned_up` | Workspace has been cleaned up |
+| `worktree:added` | Git worktree added to parent |
+| `worktree:removed` | Git worktree removed |
 | `credential:granted` | Credential was granted |
 | `credential:revoked` | Credential was revoked |
 | `pr:created` | Pull request was created |

package/dist/index.cjs

@@ -283,6 +283,22 @@ var WorkspaceService = class {
    * Provision a new workspace for a task
    */
   async provision(config) {
+    const strategy = config.strategy || "clone";
+    if (strategy === "worktree") {
+      if (!config.parentWorkspace) {
+        throw new Error('parentWorkspace is required when strategy is "worktree"');
+      }
+      const parent = this.workspaces.get(config.parentWorkspace);
+      if (!parent) {
+        throw new Error(`Parent workspace not found: ${config.parentWorkspace}`);
+      }
+      if (parent.strategy !== "clone") {
+        throw new Error("Parent workspace must be a clone, not a worktree");
+      }
+      if (parent.repo !== config.repo) {
+        throw new Error("Worktree must be for the same repository as parent");
+      }
+    }
     const workspaceId = crypto.randomUUID();
     this.log(
       "info",
@@ -290,7 +306,8 @@ var WorkspaceService = class {
         workspaceId,
         repo: config.repo,
         executionId: config.execution.id,
-        role: config.task.role
+        role: config.task.role,
+        strategy
       },
       "Provisioning workspace"
     );
@@ -301,26 +318,31 @@ var WorkspaceService = class {
       timestamp: /* @__PURE__ */ new Date()
     });
     const workspacePath = path__namespace.join(this.baseDir, workspaceId);
-    await fs3__namespace.mkdir(workspacePath, { recursive: true });
-    const credential = await this.credentialService.getCredentials({
-      repo: config.repo,
-      access: "write",
-      context: {
+    let credential;
+    if (strategy === "worktree" && config.parentWorkspace) {
+      const parent = this.workspaces.get(config.parentWorkspace);
+      credential = parent.credential;
+    } else {
+      await fs3__namespace.mkdir(workspacePath, { recursive: true });
+      credential = await this.credentialService.getCredentials({
+        repo: config.repo,
+        access: "write",
+        context: {
+          executionId: config.execution.id,
+          taskId: config.task.id,
+          userId: config.user?.id,
+          reason: `Workspace for ${config.task.role} in ${config.execution.patternName}`
+        },
+        userProvided: config.userCredentials
+      });
+      await this.emitEvent({
+        type: "credential:granted",
+        workspaceId,
+        credentialId: credential.id,
         executionId: config.execution.id,
-        taskId: config.task.id,
-        userId: config.user?.id,
-        reason: `Workspace for ${config.task.role} in ${config.execution.patternName}`
-      },
-      // Pass user-provided credentials if available
-      userProvided: config.userCredentials
-    });
-    await this.emitEvent({
-      type: "credential:granted",
-      workspaceId,
-      credentialId: credential.id,
-      executionId: config.execution.id,
-      timestamp: /* @__PURE__ */ new Date()
-    });
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    }
     const branchInfo = createBranchInfo(
       {
         executionId: config.execution.id,
@@ -337,21 +359,52 @@ var WorkspaceService = class {
       branch: branchInfo,
       credential,
       provisionedAt: /* @__PURE__ */ new Date(),
-      status: "provisioning"
+      status: "provisioning",
+      strategy,
+      parentWorkspaceId: config.parentWorkspace,
+      onComplete: config.onComplete,
+      progress: {
+        phase: "initializing",
+        message: "Initializing workspace",
+        updatedAt: /* @__PURE__ */ new Date()
+      }
     };
     this.workspaces.set(workspaceId, workspace);
     try {
-      await this.cloneRepo(workspace, credential.token);
-      await this.createBranch(workspace);
+      if (strategy === "clone") {
+        this.updateProgress(workspace, "cloning", "Cloning repository");
+        await this.cloneRepo(workspace, credential.token);
+        this.updateProgress(workspace, "creating_branch", "Creating branch");
+        await this.createBranch(workspace);
+      } else {
+        const parent = this.workspaces.get(config.parentWorkspace);
+        await this.addWorktreeFromParent(parent, workspace);
+        if (!parent.worktreeIds) {
+          parent.worktreeIds = [];
+        }
+        parent.worktreeIds.push(workspaceId);
+        this.workspaces.set(parent.id, parent);
+        await this.emitEvent({
+          type: "worktree:added",
+          workspaceId,
+          executionId: config.execution.id,
+          timestamp: /* @__PURE__ */ new Date(),
+          data: { parentWorkspaceId: parent.id }
+        });
+      }
+      this.updateProgress(workspace, "configuring", "Configuring git");
       await this.configureGit(workspace);
       workspace.status = "ready";
+      this.updateProgress(workspace, "ready", "Workspace ready");
       this.workspaces.set(workspaceId, workspace);
+      await this.executeCompletionHook(workspace, "success");
       this.log(
         "info",
         {
           workspaceId,
           path: workspacePath,
-          branch: branchInfo.name
+          branch: branchInfo.name,
+          strategy
         },
         "Workspace provisioned"
       );
@@ -364,8 +417,9 @@ var WorkspaceService = class {
       return workspace;
     } catch (error) {
       workspace.status = "error";
-      this.workspaces.set(workspaceId, workspace);
       const errorMessage = error instanceof Error ? error.message : String(error);
+      this.updateProgress(workspace, "error", errorMessage);
+      this.workspaces.set(workspaceId, workspace);
       this.log("error", { workspaceId, error: errorMessage }, "Failed to provision workspace");
       await this.emitEvent({
         type: "workspace:error",
@@ -374,9 +428,54 @@ var WorkspaceService = class {
         timestamp: /* @__PURE__ */ new Date(),
         error: errorMessage
       });
+      await this.executeCompletionHook(workspace, "error");
       throw error;
     }
   }
+  /**
+   * Add a worktree to an existing clone workspace (convenience method)
+   */
+  async addWorktree(parentWorkspaceId, options) {
+    const parent = this.workspaces.get(parentWorkspaceId);
+    if (!parent) {
+      throw new Error(`Parent workspace not found: ${parentWorkspaceId}`);
+    }
+    return this.provision({
+      repo: parent.repo,
+      strategy: "worktree",
+      parentWorkspace: parentWorkspaceId,
+      branchStrategy: "feature_branch",
+      baseBranch: options.branch,
+      execution: options.execution,
+      task: options.task
+    });
+  }
+  /**
+   * List all worktrees for a parent workspace
+   */
+  listWorktrees(parentWorkspaceId) {
+    const parent = this.workspaces.get(parentWorkspaceId);
+    if (!parent) {
+      return [];
+    }
+    if (!parent.worktreeIds || parent.worktreeIds.length === 0) {
+      return [];
+    }
+    return parent.worktreeIds.map((id) => this.workspaces.get(id)).filter((w) => w !== void 0);
+  }
+  /**
+   * Remove a worktree (alias for cleanup with worktree-specific handling)
+   */
+  async removeWorktree(workspaceId) {
+    const workspace = this.workspaces.get(workspaceId);
+    if (!workspace) {
+      return;
+    }
+    if (workspace.strategy !== "worktree") {
+      throw new Error("Workspace is not a worktree. Use cleanup() instead.");
+    }
+    await this.cleanup(workspaceId);
+  }
   /**
    * Finalize a workspace (push, create PR, cleanup)
    */
@@ -456,21 +555,55 @@ var WorkspaceService = class {
     if (!workspace) {
       return;
     }
-    this.log("info", { workspaceId }, "Cleaning up workspace");
+    this.log("info", { workspaceId, strategy: workspace.strategy }, "Cleaning up workspace");
+    if (workspace.strategy === "clone" && workspace.worktreeIds?.length) {
+      this.log(
+        "info",
+        { workspaceId, worktreeCount: workspace.worktreeIds.length },
+        "Cleaning up child worktrees first"
+      );
+      for (const worktreeId of workspace.worktreeIds) {
+        await this.cleanup(worktreeId);
+      }
+    }
     try {
       await cleanupCredentialFiles(workspace.path);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       this.log("warn", { workspaceId, error: errorMessage }, "Failed to clean up credential files");
     }
-    await this.credentialService.revokeCredential(workspace.credential.id);
-    await this.emitEvent({
-      type: "credential:revoked",
-      workspaceId,
-      credentialId: workspace.credential.id,
-      executionId: workspace.branch.executionId,
-      timestamp: /* @__PURE__ */ new Date()
-    });
+    if (workspace.strategy === "worktree" && workspace.parentWorkspaceId) {
+      const parent = this.workspaces.get(workspace.parentWorkspaceId);
+      if (parent) {
+        try {
+          await this.execInDir(parent.path, `git worktree remove "${workspace.path}" --force`);
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          this.log("warn", { workspaceId, error: errorMessage }, "Failed to remove worktree via git");
+        }
+        if (parent.worktreeIds) {
+          parent.worktreeIds = parent.worktreeIds.filter((id) => id !== workspaceId);
+          this.workspaces.set(parent.id, parent);
+        }
+        await this.emitEvent({
+          type: "worktree:removed",
+          workspaceId,
+          executionId: workspace.branch.executionId,
+          timestamp: /* @__PURE__ */ new Date(),
+          data: { parentWorkspaceId: parent.id }
+        });
+      }
+    }
+    if (workspace.strategy === "clone") {
+      await this.credentialService.revokeCredential(workspace.credential.id);
+      await this.emitEvent({
+        type: "credential:revoked",
+        workspaceId,
+        credentialId: workspace.credential.id,
+        executionId: workspace.branch.executionId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    }
     try {
       await fs3__namespace.rm(workspace.path, { recursive: true, force: true });
     } catch (error) {
@@ -507,6 +640,16 @@ var WorkspaceService = class {
   async createBranch(workspace) {
     await this.execInDir(workspace.path, `git checkout -b ${workspace.branch.name}`);
   }
+  async addWorktreeFromParent(parent, workspace) {
+    try {
+      await this.execInDir(parent.path, `git fetch origin ${workspace.branch.baseBranch}`);
+    } catch {
+    }
+    await this.execInDir(
+      parent.path,
+      `git worktree add -b ${workspace.branch.name} "${workspace.path}" origin/${workspace.branch.baseBranch}`
+    );
+  }
   async configureGit(workspace) {
     await this.execInDir(workspace.path, 'git config user.name "Workspace Agent"');
     await this.execInDir(workspace.path, 'git config user.email "agent@workspace.local"');
@@ -622,6 +765,72 @@ var WorkspaceService = class {
       }
     }
   }
+  /**
+   * Update workspace progress
+   */
+  updateProgress(workspace, phase, message) {
+    workspace.progress = {
+      phase,
+      message,
+      updatedAt: /* @__PURE__ */ new Date()
+    };
+    this.workspaces.set(workspace.id, workspace);
+    this.log(
+      "debug",
+      { workspaceId: workspace.id, phase, message },
+      "Progress updated"
+    );
+  }
+  /**
+   * Execute completion hook if configured
+   */
+  async executeCompletionHook(workspace, status) {
+    const hook = workspace.onComplete;
+    if (!hook) return;
+    if (status === "error" && hook.runOnError === false) {
+      return;
+    }
+    const env = {
+      ...process.env,
+      WORKSPACE_ID: workspace.id,
+      REPO: workspace.repo,
+      BRANCH: workspace.branch.name,
+      STATUS: status,
+      WORKSPACE_PATH: workspace.path
+    };
+    if (hook.command) {
+      try {
+        this.log("info", { workspaceId: workspace.id, command: hook.command }, "Executing completion hook command");
+        await execAsync(hook.command, { env });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.log("warn", { workspaceId: workspace.id, error: errorMessage }, "Completion hook command failed");
+      }
+    }
+    if (hook.webhook) {
+      try {
+        this.log("info", { workspaceId: workspace.id, webhook: hook.webhook }, "Calling completion webhook");
+        const payload = {
+          workspaceId: workspace.id,
+          repo: workspace.repo,
+          branch: workspace.branch.name,
+          status,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await fetch(hook.webhook, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...hook.webhookHeaders
+          },
+          body: JSON.stringify(payload)
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.log("warn", { workspaceId: workspace.id, error: errorMessage }, "Completion webhook failed");
+      }
+    }
+  }
 };
 
 // src/oauth/device-flow.ts