git-workspace-service 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -175,7 +175,60 @@ interface CredentialGrant {
     lastUsedAt?: Date;
 }
 type BranchStrategy = 'feature_branch' | 'fork' | 'direct';
+/**
+ * Workspace provisioning strategy
+ * - 'clone': Full clone of the repository (default)
+ * - 'worktree': Git worktree from an existing clone (faster, shared .git)
+ */
+type WorkspaceStrategy = 'clone' | 'worktree';
 type WorkspaceStatus = 'provisioning' | 'ready' | 'in_use' | 'finalizing' | 'cleaned_up' | 'error';
+/**
+ * Granular progress phases for workspace operations
+ */
+type WorkspacePhase = 'initializing' | 'cloning' | 'creating_branch' | 'configuring' | 'ready' | 'committing' | 'pushing' | 'creating_pr' | 'cleaning_up' | 'done' | 'error';
+/**
+ * Progress tracking for workspace operations
+ */
+interface WorkspaceProgress {
+    /**
+     * Current phase of the operation
+     */
+    phase: WorkspacePhase;
+    /**
+     * Human-readable message describing current activity
+     */
+    message?: string;
+    /**
+     * Progress percentage (0-100) if determinable
+     */
+    percent?: number;
+    /**
+     * When progress was last updated
+     */
+    updatedAt: Date;
+}
+/**
+ * Completion hook configuration
+ */
+interface CompletionHook {
+    /**
+     * Shell command to execute on completion
+     * Variables available: $WORKSPACE_ID, $REPO, $BRANCH, $STATUS
+     */
+    command?: string;
+    /**
+     * Webhook URL to POST to on completion
+     */
+    webhook?: string;
+    /**
+     * Custom headers for webhook request
+     */
+    webhookHeaders?: Record<string, string>;
+    /**
+     * Whether to run hook on error (default: true)
+     */
+    runOnError?: boolean;
+}
 /**
  * Configuration for provisioning a workspace
  */
@@ -188,6 +241,16 @@ interface WorkspaceConfig {
      * Git provider
      */
     provider?: GitProvider;
+    /**
+     * Workspace strategy: 'clone' (default) or 'worktree'
+     * Worktrees are faster and use less disk space for parallel work on same repo
+     */
+    strategy?: WorkspaceStrategy;
+    /**
+     * Parent workspace ID (required when strategy is 'worktree')
+     * The parent must be a 'clone' workspace for the same repo
+     */
+    parentWorkspace?: string;
     /**
      * Branch strategy
      */
@@ -223,6 +286,10 @@ interface WorkspaceConfig {
      * If provided, these are used instead of managed credentials
      */
     userCredentials?: UserProvidedCredentials;
+    /**
+     * Hook to run when workspace operations complete
+     */
+    onComplete?: CompletionHook;
 }
 /**
  * A provisioned git workspace
@@ -256,6 +323,26 @@ interface Workspace {
      * Current status
      */
     status: WorkspaceStatus;
+    /**
+     * Workspace strategy used ('clone' or 'worktree')
+     */
+    strategy: WorkspaceStrategy;
+    /**
+     * Parent workspace ID (for worktrees)
+     */
+    parentWorkspaceId?: string;
+    /**
+     * Child worktree IDs (for clone workspaces that have worktrees)
+     */
+    worktreeIds?: string[];
+    /**
+     * Current progress of workspace operations
+     */
+    progress?: WorkspaceProgress;
+    /**
+     * Completion hook configuration
+     */
+    onComplete?: CompletionHook;
 }
 /**
  * Options for finalizing a workspace (push, PR creation, cleanup)
@@ -731,7 +818,7 @@ interface GitProviderAdapter {
      */
     getDefaultBranch(repo: string, credential: GitCredential): Promise<string>;
 }
-type WorkspaceEventType = 'workspace:provisioning' | 'workspace:ready' | 'workspace:error' | 'workspace:finalizing' | 'workspace:cleaned_up' | 'credential:granted' | 'credential:revoked' | 'pr:created' | 'pr:merged';
+type WorkspaceEventType = 'workspace:provisioning' | 'workspace:ready' | 'workspace:error' | 'workspace:finalizing' | 'workspace:cleaned_up' | 'worktree:added' | 'worktree:removed' | 'credential:granted' | 'credential:revoked' | 'pr:created' | 'pr:merged';
 interface WorkspaceEvent {
     type: WorkspaceEventType;
     workspaceId?: string;
@@ -1103,6 +1190,29 @@ declare class WorkspaceService {
      * Provision a new workspace for a task
      */
     provision(config: WorkspaceConfig): Promise<Workspace>;
+    /**
+     * Add a worktree to an existing clone workspace (convenience method)
+     */
+    addWorktree(parentWorkspaceId: string, options: {
+        branch: string;
+        execution: {
+            id: string;
+            patternName: string;
+        };
+        task: {
+            id: string;
+            role: string;
+            slug?: string;
+        };
+    }): Promise<Workspace>;
+    /**
+     * List all worktrees for a parent workspace
+     */
+    listWorktrees(parentWorkspaceId: string): Workspace[];
+    /**
+     * Remove a worktree (alias for cleanup with worktree-specific handling)
+     */
+    removeWorktree(workspaceId: string): Promise<void>;
     /**
      * Finalize a workspace (push, create PR, cleanup)
      */
@@ -1125,6 +1235,7 @@ declare class WorkspaceService {
     cleanupForExecution(executionId: string): Promise<void>;
     private cloneRepo;
     private createBranch;
+    private addWorktreeFromParent;
     private configureGit;
     private pushBranch;
     private createPullRequest;
@@ -1133,6 +1244,14 @@ declare class WorkspaceService {
     private execInDir;
     private log;
     private emitEvent;
+    /**
+     * Update workspace progress
+     */
+    private updateProgress;
+    /**
+     * Execute completion hook if configured
+     */
+    private executeCompletionHook;
 }
 
 /**
@@ -1515,4 +1634,4 @@ declare function getGitCredentialConfig(helperScriptPath: string): string[];
  */
 declare function outputCredentials(username: string, password: string): void;
 
-export { type AgentPermissions, type AuthPrompt, type AuthPromptEmitter, type AuthResult, type BranchConfig, type BranchInfo, type BranchNamingOptions, type BranchStrategy, type CreateIssueOptions, type CredentialContext, type CredentialGrant, type CredentialGrantStore, type CredentialHelperContext, CredentialService, type CredentialServiceConfig, type CredentialServiceLogger, type CredentialServiceOptions, type CredentialType, DEFAULT_AGENT_PERMISSIONS, DEFAULT_BRANCH_PREFIX, type DeviceCodeResponse, FileTokenStore, type GitCredential, type GitCredentialRequest, type GitHubAppConfig, type GitHubAppInstallation, GitHubPatClient, type GitHubPatClientLogger, type GitHubPatClientOptions, GitHubProvider, type GitHubProviderConfig, type GitHubProviderLogger, type GitProvider, type GitProviderAdapter, type IssueComment, type IssueCommentOptions, type IssueInfo, type IssueState, MemoryTokenStore, OAuthDeviceFlow, type OAuthDeviceFlowConfig, type OAuthDeviceFlowLogger, type OAuthToken, type PermissionLevel, type PullRequestInfo, READONLY_AGENT_PERMISSIONS, type RepositoryScope, type SshCredentials, type TokenCredentials, TokenStore, type TokenStoreOptions, type UserProvidedCredentials, type Workspace, type WorkspaceConfig, type WorkspaceEvent, type WorkspaceEventHandler, type WorkspaceEventType, type WorkspaceFinalization, WorkspaceService, type WorkspaceServiceConfig, type WorkspaceServiceLogger, type WorkspaceServiceOptions, type WorkspaceStatus, cleanupCredentialFiles, configureCredentialHelper, createBranchInfo, createNodeCredentialHelperScript, createShellCredentialHelperScript, filterBranchesByExecution, generateBranchName, generateSlug, getGitCredentialConfig, isManagedBranch, outputCredentials, parseBranchName, updateCredentials };
+export { type AgentPermissions, type AuthPrompt, type AuthPromptEmitter, type AuthResult, type BranchConfig, type BranchInfo, type BranchNamingOptions, type BranchStrategy, type CompletionHook, type CreateIssueOptions, type CredentialContext, type CredentialGrant, type CredentialGrantStore, type CredentialHelperContext, CredentialService, type CredentialServiceConfig, type CredentialServiceLogger, type CredentialServiceOptions, type CredentialType, DEFAULT_AGENT_PERMISSIONS, DEFAULT_BRANCH_PREFIX, type DeviceCodeResponse, FileTokenStore, type GitCredential, type GitCredentialRequest, type GitHubAppConfig, type GitHubAppInstallation, GitHubPatClient, type GitHubPatClientLogger, type GitHubPatClientOptions, GitHubProvider, type GitHubProviderConfig, type GitHubProviderLogger, type GitProvider, type GitProviderAdapter, type IssueComment, type IssueCommentOptions, type IssueInfo, type IssueState, MemoryTokenStore, OAuthDeviceFlow, type OAuthDeviceFlowConfig, type OAuthDeviceFlowLogger, type OAuthToken, type PermissionLevel, type PullRequestInfo, READONLY_AGENT_PERMISSIONS, type RepositoryScope, type SshCredentials, type TokenCredentials, TokenStore, type TokenStoreOptions, type UserProvidedCredentials, type Workspace, type WorkspaceConfig, type WorkspaceEvent, type WorkspaceEventHandler, type WorkspaceEventType, type WorkspaceFinalization, type WorkspacePhase, type WorkspaceProgress, WorkspaceService, type WorkspaceServiceConfig, type WorkspaceServiceLogger, type WorkspaceServiceOptions, type WorkspaceStatus, type WorkspaceStrategy, cleanupCredentialFiles, configureCredentialHelper, createBranchInfo, createNodeCredentialHelperScript, createShellCredentialHelperScript, filterBranchesByExecution, generateBranchName, generateSlug, getGitCredentialConfig, isManagedBranch, outputCredentials, parseBranchName, updateCredentials };

package/dist/index.d.ts

@@ -175,7 +175,60 @@ interface CredentialGrant {
     lastUsedAt?: Date;
 }
 type BranchStrategy = 'feature_branch' | 'fork' | 'direct';
+/**
+ * Workspace provisioning strategy
+ * - 'clone': Full clone of the repository (default)
+ * - 'worktree': Git worktree from an existing clone (faster, shared .git)
+ */
+type WorkspaceStrategy = 'clone' | 'worktree';
 type WorkspaceStatus = 'provisioning' | 'ready' | 'in_use' | 'finalizing' | 'cleaned_up' | 'error';
+/**
+ * Granular progress phases for workspace operations
+ */
+type WorkspacePhase = 'initializing' | 'cloning' | 'creating_branch' | 'configuring' | 'ready' | 'committing' | 'pushing' | 'creating_pr' | 'cleaning_up' | 'done' | 'error';
+/**
+ * Progress tracking for workspace operations
+ */
+interface WorkspaceProgress {
+    /**
+     * Current phase of the operation
+     */
+    phase: WorkspacePhase;
+    /**
+     * Human-readable message describing current activity
+     */
+    message?: string;
+    /**
+     * Progress percentage (0-100) if determinable
+     */
+    percent?: number;
+    /**
+     * When progress was last updated
+     */
+    updatedAt: Date;
+}
+/**
+ * Completion hook configuration
+ */
+interface CompletionHook {
+    /**
+     * Shell command to execute on completion
+     * Variables available: $WORKSPACE_ID, $REPO, $BRANCH, $STATUS
+     */
+    command?: string;
+    /**
+     * Webhook URL to POST to on completion
+     */
+    webhook?: string;
+    /**
+     * Custom headers for webhook request
+     */
+    webhookHeaders?: Record<string, string>;
+    /**
+     * Whether to run hook on error (default: true)
+     */
+    runOnError?: boolean;
+}
 /**
  * Configuration for provisioning a workspace
  */
@@ -188,6 +241,16 @@ interface WorkspaceConfig {
      * Git provider
      */
     provider?: GitProvider;
+    /**
+     * Workspace strategy: 'clone' (default) or 'worktree'
+     * Worktrees are faster and use less disk space for parallel work on same repo
+     */
+    strategy?: WorkspaceStrategy;
+    /**
+     * Parent workspace ID (required when strategy is 'worktree')
+     * The parent must be a 'clone' workspace for the same repo
+     */
+    parentWorkspace?: string;
     /**
      * Branch strategy
      */
@@ -223,6 +286,10 @@ interface WorkspaceConfig {
      * If provided, these are used instead of managed credentials
      */
     userCredentials?: UserProvidedCredentials;
+    /**
+     * Hook to run when workspace operations complete
+     */
+    onComplete?: CompletionHook;
 }
 /**
  * A provisioned git workspace
@@ -256,6 +323,26 @@ interface Workspace {
      * Current status
      */
     status: WorkspaceStatus;
+    /**
+     * Workspace strategy used ('clone' or 'worktree')
+     */
+    strategy: WorkspaceStrategy;
+    /**
+     * Parent workspace ID (for worktrees)
+     */
+    parentWorkspaceId?: string;
+    /**
+     * Child worktree IDs (for clone workspaces that have worktrees)
+     */
+    worktreeIds?: string[];
+    /**
+     * Current progress of workspace operations
+     */
+    progress?: WorkspaceProgress;
+    /**
+     * Completion hook configuration
+     */
+    onComplete?: CompletionHook;
 }
 /**
  * Options for finalizing a workspace (push, PR creation, cleanup)
@@ -731,7 +818,7 @@ interface GitProviderAdapter {
      */
     getDefaultBranch(repo: string, credential: GitCredential): Promise<string>;
 }
-type WorkspaceEventType = 'workspace:provisioning' | 'workspace:ready' | 'workspace:error' | 'workspace:finalizing' | 'workspace:cleaned_up' | 'credential:granted' | 'credential:revoked' | 'pr:created' | 'pr:merged';
+type WorkspaceEventType = 'workspace:provisioning' | 'workspace:ready' | 'workspace:error' | 'workspace:finalizing' | 'workspace:cleaned_up' | 'worktree:added' | 'worktree:removed' | 'credential:granted' | 'credential:revoked' | 'pr:created' | 'pr:merged';
 interface WorkspaceEvent {
     type: WorkspaceEventType;
     workspaceId?: string;
@@ -1103,6 +1190,29 @@ declare class WorkspaceService {
      * Provision a new workspace for a task
      */
     provision(config: WorkspaceConfig): Promise<Workspace>;
+    /**
+     * Add a worktree to an existing clone workspace (convenience method)
+     */
+    addWorktree(parentWorkspaceId: string, options: {
+        branch: string;
+        execution: {
+            id: string;
+            patternName: string;
+        };
+        task: {
+            id: string;
+            role: string;
+            slug?: string;
+        };
+    }): Promise<Workspace>;
+    /**
+     * List all worktrees for a parent workspace
+     */
+    listWorktrees(parentWorkspaceId: string): Workspace[];
+    /**
+     * Remove a worktree (alias for cleanup with worktree-specific handling)
+     */
+    removeWorktree(workspaceId: string): Promise<void>;
     /**
      * Finalize a workspace (push, create PR, cleanup)
      */
@@ -1125,6 +1235,7 @@ declare class WorkspaceService {
     cleanupForExecution(executionId: string): Promise<void>;
     private cloneRepo;
     private createBranch;
+    private addWorktreeFromParent;
     private configureGit;
     private pushBranch;
     private createPullRequest;
@@ -1133,6 +1244,14 @@ declare class WorkspaceService {
     private execInDir;
     private log;
     private emitEvent;
+    /**
+     * Update workspace progress
+     */
+    private updateProgress;
+    /**
+     * Execute completion hook if configured
+     */
+    private executeCompletionHook;
 }
 
 /**
@@ -1515,4 +1634,4 @@ declare function getGitCredentialConfig(helperScriptPath: string): string[];
  */
 declare function outputCredentials(username: string, password: string): void;
 
-export { type AgentPermissions, type AuthPrompt, type AuthPromptEmitter, type AuthResult, type BranchConfig, type BranchInfo, type BranchNamingOptions, type BranchStrategy, type CreateIssueOptions, type CredentialContext, type CredentialGrant, type CredentialGrantStore, type CredentialHelperContext, CredentialService, type CredentialServiceConfig, type CredentialServiceLogger, type CredentialServiceOptions, type CredentialType, DEFAULT_AGENT_PERMISSIONS, DEFAULT_BRANCH_PREFIX, type DeviceCodeResponse, FileTokenStore, type GitCredential, type GitCredentialRequest, type GitHubAppConfig, type GitHubAppInstallation, GitHubPatClient, type GitHubPatClientLogger, type GitHubPatClientOptions, GitHubProvider, type GitHubProviderConfig, type GitHubProviderLogger, type GitProvider, type GitProviderAdapter, type IssueComment, type IssueCommentOptions, type IssueInfo, type IssueState, MemoryTokenStore, OAuthDeviceFlow, type OAuthDeviceFlowConfig, type OAuthDeviceFlowLogger, type OAuthToken, type PermissionLevel, type PullRequestInfo, READONLY_AGENT_PERMISSIONS, type RepositoryScope, type SshCredentials, type TokenCredentials, TokenStore, type TokenStoreOptions, type UserProvidedCredentials, type Workspace, type WorkspaceConfig, type WorkspaceEvent, type WorkspaceEventHandler, type WorkspaceEventType, type WorkspaceFinalization, WorkspaceService, type WorkspaceServiceConfig, type WorkspaceServiceLogger, type WorkspaceServiceOptions, type WorkspaceStatus, cleanupCredentialFiles, configureCredentialHelper, createBranchInfo, createNodeCredentialHelperScript, createShellCredentialHelperScript, filterBranchesByExecution, generateBranchName, generateSlug, getGitCredentialConfig, isManagedBranch, outputCredentials, parseBranchName, updateCredentials };
+export { type AgentPermissions, type AuthPrompt, type AuthPromptEmitter, type AuthResult, type BranchConfig, type BranchInfo, type BranchNamingOptions, type BranchStrategy, type CompletionHook, type CreateIssueOptions, type CredentialContext, type CredentialGrant, type CredentialGrantStore, type CredentialHelperContext, CredentialService, type CredentialServiceConfig, type CredentialServiceLogger, type CredentialServiceOptions, type CredentialType, DEFAULT_AGENT_PERMISSIONS, DEFAULT_BRANCH_PREFIX, type DeviceCodeResponse, FileTokenStore, type GitCredential, type GitCredentialRequest, type GitHubAppConfig, type GitHubAppInstallation, GitHubPatClient, type GitHubPatClientLogger, type GitHubPatClientOptions, GitHubProvider, type GitHubProviderConfig, type GitHubProviderLogger, type GitProvider, type GitProviderAdapter, type IssueComment, type IssueCommentOptions, type IssueInfo, type IssueState, MemoryTokenStore, OAuthDeviceFlow, type OAuthDeviceFlowConfig, type OAuthDeviceFlowLogger, type OAuthToken, type PermissionLevel, type PullRequestInfo, READONLY_AGENT_PERMISSIONS, type RepositoryScope, type SshCredentials, type TokenCredentials, TokenStore, type TokenStoreOptions, type UserProvidedCredentials, type Workspace, type WorkspaceConfig, type WorkspaceEvent, type WorkspaceEventHandler, type WorkspaceEventType, type WorkspaceFinalization, type WorkspacePhase, type WorkspaceProgress, WorkspaceService, type WorkspaceServiceConfig, type WorkspaceServiceLogger, type WorkspaceServiceOptions, type WorkspaceStatus, type WorkspaceStrategy, cleanupCredentialFiles, configureCredentialHelper, createBranchInfo, createNodeCredentialHelperScript, createShellCredentialHelperScript, filterBranchesByExecution, generateBranchName, generateSlug, getGitCredentialConfig, isManagedBranch, outputCredentials, parseBranchName, updateCredentials };