@assistkick/create 1.7.0 → 1.8.0

package/templates/assistkick-product-system/packages/backend/src/services/bundle_service.ts

@@ -0,0 +1,182 @@
+/**
+ * BundleService — manages the Remotion bundle for the video package.
+ *
+ * Responsibilities:
+ * - Build the Remotion bundle from the video package (via @remotion/bundler)
+ * - Track bundle status (ready, building, last built timestamp)
+ * - Scan the compositions directory for available compositions and metadata
+ * - Serve bundle path for static file serving
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+
+interface BundleServiceDeps {
+  videoPackageDir: string;
+  bundleOutputDir: string;
+  log: (tag: string, ...args: any[]) => void;
+}
+
+export interface CompositionMeta {
+  id: string;
+  durationInFrames: number;
+  fps: number;
+  width: number;
+  height: number;
+  folder?: string;
+}
+
+export interface BundleStatus {
+  ready: boolean;
+  building: boolean;
+  bundlePath: string | null;
+  lastBuiltAt: string | null;
+  error: string | null;
+}
+
+export class BundleService {
+  private readonly videoPackageDir: string;
+  private readonly bundleOutputDir: string;
+  private readonly log: BundleServiceDeps['log'];
+  private building = false;
+  private lastBuiltAt: string | null = null;
+  private lastError: string | null = null;
+
+  constructor({ videoPackageDir, bundleOutputDir, log }: BundleServiceDeps) {
+    this.videoPackageDir = videoPackageDir;
+    this.bundleOutputDir = bundleOutputDir;
+    this.log = log;
+  }
+
+  /** Returns the directory path where the built bundle is stored. */
+  getBundleDir = (): string => {
+    return this.bundleOutputDir;
+  };
+
+  /** Check if a bundle has been built and exists on disk. */
+  isBundleReady = (): boolean => {
+    return existsSync(join(this.bundleOutputDir, 'index.html'));
+  };
+
+  /** Returns current bundle status. */
+  getStatus = (): BundleStatus => {
+    return {
+      ready: this.isBundleReady(),
+      building: this.building,
+      bundlePath: this.isBundleReady() ? this.bundleOutputDir : null,
+      lastBuiltAt: this.lastBuiltAt,
+      error: this.lastError,
+    };
+  };
+
+  /**
+   * Build the Remotion bundle from the video package.
+   * Uses the Remotion CLI to create a webpack bundle.
+   */
+  buildBundle = async (): Promise<BundleStatus> => {
+    if (this.building) {
+      this.log('BUNDLE', 'Bundle build already in progress');
+      return this.getStatus();
+    }
+
+    this.building = true;
+    this.lastError = null;
+    this.log('BUNDLE', `Building Remotion bundle from ${this.videoPackageDir}`);
+
+    try {
+      await this.spawnBundler();
+      this.lastBuiltAt = new Date().toISOString();
+      this.log('BUNDLE', `Bundle built successfully at ${this.lastBuiltAt}`);
+    } catch (err: any) {
+      this.lastError = err.message;
+      this.log('BUNDLE', `Bundle build failed: ${err.message}`);
+    } finally {
+      this.building = false;
+    }
+
+    return this.getStatus();
+  };
+
+  /**
+   * Scan the video package's compositions/ directory and extract metadata
+   * from each composition's index.tsx file.
+   */
+  listCompositions = (): CompositionMeta[] => {
+    const compositionsDir = join(this.videoPackageDir, 'compositions');
+    if (!existsSync(compositionsDir)) {
+      return [];
+    }
+
+    const entries = readdirSync(compositionsDir);
+    const compositions: CompositionMeta[] = [];
+
+    for (const entry of entries) {
+      const entryPath = join(compositionsDir, entry);
+      if (!statSync(entryPath).isDirectory()) continue;
+
+      const indexPath = join(entryPath, 'index.tsx');
+      if (!existsSync(indexPath)) continue;
+
+      const meta = this.parseCompositionMeta(indexPath);
+      if (meta) {
+        compositions.push(meta);
+      }
+    }
+
+    return compositions;
+  };
+
+  /**
+   * Parse a composition's index.tsx file to extract exported metadata.
+   * Uses regex to find exported const values for id, fps, width, height, etc.
+   */
+  private parseCompositionMeta = (filePath: string): CompositionMeta | null => {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+
+      const idMatch = content.match(/export\s+const\s+id\s*=\s*['"]([^'"]+)['"]/);
+      if (!idMatch) return null;
+
+      const durationMatch = content.match(/export\s+const\s+durationInFrames\s*=\s*(\d+)/);
+      const fpsMatch = content.match(/export\s+const\s+fps\s*=\s*(\d+)/);
+      const widthMatch = content.match(/export\s+const\s+width\s*=\s*(\d+)/);
+      const heightMatch = content.match(/export\s+const\s+height\s*=\s*(\d+)/);
+      const folderMatch = content.match(/export\s+const\s+folder\s*=\s*['"]([^'"]+)['"]/);
+
+      return {
+        id: idMatch[1],
+        durationInFrames: durationMatch ? parseInt(durationMatch[1], 10) : 300,
+        fps: fpsMatch ? parseInt(fpsMatch[1], 10) : 30,
+        width: widthMatch ? parseInt(widthMatch[1], 10) : 1920,
+        height: heightMatch ? parseInt(heightMatch[1], 10) : 1080,
+        folder: folderMatch ? folderMatch[1] : undefined,
+      };
+    } catch {
+      return null;
+    }
+  };
+
+  private spawnBundler = (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      const entryPoint = join(this.videoPackageDir, 'index.ts');
+      execFile('npx', [
+        'remotion', 'bundle',
+        entryPoint,
+        '--out-dir', this.bundleOutputDir,
+        '--log', 'warn',
+      ], {
+        cwd: this.videoPackageDir,
+        timeout: 300_000,
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env },
+      }, (error, _stdout, stderr) => {
+        if (error) {
+          reject(new Error(`Remotion bundle failed: ${error.message}${stderr ? `\n${stderr}` : ''}`));
+          return;
+        }
+        resolve();
+      });
+    });
+  };
+}

package/templates/assistkick-product-system/packages/backend/src/services/init.ts

@@ -1,24 +1,22 @@
 /**
- * Service initialization — creates pipeline, claude service, and related instances.
+ * Service initialization — creates workflow engine, claude service, and related instances.
  * Deferred until VERBOSE flag is set at startup.
  */
 
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
 import { createClaudeService } from '@assistkick/shared/lib/claude-service.js';
-import { Pipeline } from '@assistkick/shared/lib/pipeline.js';
-import { PipelineStateStore } from '@assistkick/shared/lib/pipeline-state-store.js';
-import { PromptBuilder } from '@assistkick/shared/lib/prompt_builder.js';
 import { GitWorkflow } from '@assistkick/shared/lib/git_workflow.js';
 import { getDb } from '@assistkick/shared/lib/db.js';
 import { loadKanban, getKanbanEntry, saveKanbanEntry } from '@assistkick/shared/lib/kanban.js';
-import { readGraph, getNode } from '@assistkick/shared/lib/graph.js';
-import { WorkSummaryParser } from '@assistkick/shared/lib/work_summary_parser.js';
-import { PipelineOrchestrator } from '@assistkick/shared/lib/pipeline_orchestrator.js';
+import { readGraph } from '@assistkick/shared/lib/graph.js';
+import { WorkflowEngine } from '@assistkick/shared/lib/workflow_engine.js';
+import { WorkflowOrchestrator } from '@assistkick/shared/lib/workflow_orchestrator.js';
+import { WorkflowService } from './workflow_service.js';
+import { WorkflowGroupService } from './workflow_group_service.js';
 import { GitHubAppService } from './github_app_service.js';
 import { ProjectWorkspaceService } from './project_workspace_service.js';
-import { ProjectService } from './project_service.js';
+import { SshKeyService } from './ssh_key_service.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Navigate from packages/backend/src/services/ up to assistkick-product-system/
@@ -32,6 +30,7 @@ const TOOLS_DIR = IS_DEV ? join(SHARED_DIR, 'tools') : join(__dirname, '..', '..
 const DATA_DIR = SHARED_DIR;
 const PROJECT_ROOT = join(SKILL_ROOT, '..');
 const SKILLS_DIR = join(PROJECT_ROOT, '.claude', 'skills');
+const WORKSPACES_DIR = process.env.WORKSPACES_DIR || join(PROJECT_ROOT, 'workspaces');
 const WORKTREES_DIR = join(PROJECT_ROOT, '.worktrees');
 const DEVELOPER_SKILL_PATH = join(SKILLS_DIR, 'product-developer', 'SKILL.md');
 const REVIEWER_SKILL_PATH = join(SKILLS_DIR, 'product-code-reviewer', 'SKILL.md');
@@ -43,14 +42,17 @@ export const log = (tag: string, ...args: any[]) => {
 };
 
 export let claudeService: any;
-export let pipeline: any;
-export let pipelineStateStore: any;
-export let orchestrator: PipelineOrchestrator;
+export let workflowEngine: WorkflowEngine;
+export let orchestrator: WorkflowOrchestrator;
+export let workflowService: WorkflowService;
+export let workflowGroupService: WorkflowGroupService;
 export let githubAppService: GitHubAppService;
+export let sshKeyService: SshKeyService;
 export let workspaceService: ProjectWorkspaceService;
 
 export const paths = {
   projectRoot: PROJECT_ROOT,
+  workspacesDir: WORKSPACES_DIR,
   worktreesDir: WORKTREES_DIR,
   skillsDir: SKILLS_DIR,
   toolsDir: TOOLS_DIR,
@@ -64,84 +66,32 @@ export const paths = {
 
 export const initServices = (verbose: boolean) => {
   claudeService = createClaudeService({ verbose, log });
-  pipelineStateStore = new PipelineStateStore({ getDb });
-  const promptBuilder = new PromptBuilder({ paths, log });
   const gitWorkflow = new GitWorkflow({ claudeService, projectRoot: PROJECT_ROOT, worktreesDir: WORKTREES_DIR, log });
-  const workSummaryParser = new WorkSummaryParser();
 
   // New services for project git repo integration
   githubAppService = new GitHubAppService({ log });
-  workspaceService = new ProjectWorkspaceService({ claudeService, projectRoot: PROJECT_ROOT, log });
-  const projectService = new ProjectService({ getDb, log });
+  sshKeyService = new SshKeyService({ log });
+  workspaceService = new ProjectWorkspaceService({ claudeService, workspacesDir: WORKSPACES_DIR, log, sshKeyService });
 
-  /**
-   * Resolve a project-scoped workspace for the pipeline.
-   * Returns a GitWorkflow pointing to the project workspace + an afterMerge hook
-   * that pushes to the remote. Returns null if no workspace is configured.
-   */
-  const resolveProjectWorkspace = async (projectId: string) => {
-    const project = await projectService.getById(projectId);
-    if (!project) return null;
+  // Workflow service for CRUD + default resolution
+  workflowService = new WorkflowService({ getDb, log });
+  workflowGroupService = new WorkflowGroupService({ getDb, log });
 
-    // Check if project has a workspace
-    if (!workspaceService.hasWorkspace(projectId)) {
-      // No workspace — use default behavior
-      return null;
-    }
-
-    const wsPath = workspaceService.getWorkspacePath(projectId);
-    const wsWorktreesDir = workspaceService.getWorktreesDir(projectId);
-
-    const projectGitWorkflow = new GitWorkflow({
-      claudeService,
-      projectRoot: wsPath,
-      worktreesDir: wsWorktreesDir,
-      log,
-    });
-
-    // Build afterMerge hook for pushing to remote
-    let afterMerge = null;
-    if (project.repoUrl && project.githubInstallationId && project.githubRepoFullName) {
-      afterMerge = async () => {
-        // Get a fresh token for push
-        const token = await githubAppService.getInstallationToken(project.githubInstallationId!);
-        const authUrl = `https://x-access-token:${token}@github.com/${project.githubRepoFullName}.git`;
-        await projectGitWorkflow.setRemoteUrl(authUrl);
-        try {
-          const branch = project.baseBranch || 'main';
-          await projectGitWorkflow.pushToRemote(branch);
-        } finally {
-          // Reset to non-authenticated URL
-          await projectGitWorkflow.setRemoteUrl(`https://github.com/${project.githubRepoFullName}.git`).catch(() => {});
-        }
-      };
-    }
-
-    return { gitWorkflow: projectGitWorkflow, afterMerge };
-  };
-
-  pipeline = new Pipeline({
-    promptBuilder,
-    gitWorkflow,
-    claudeService,
+  // WorkflowEngine replaces Pipeline
+  workflowEngine = new WorkflowEngine({
+    db: getDb(),
     kanban: { getKanbanEntry, saveKanbanEntry },
-    paths,
+    claudeService,
+    gitWorkflow,
     log,
-    stateStore: pipelineStateStore,
-    workSummaryParser,
-    getNode,
-    resolveProjectWorkspace,
   });
 
-  orchestrator = new PipelineOrchestrator({
-    pipeline,
+  // WorkflowOrchestrator replaces PipelineOrchestrator
+  orchestrator = new WorkflowOrchestrator({
+    workflowEngine,
     loadKanban,
     readGraph,
+    resolveDefaultWorkflow: (projectId?: string) => workflowService.resolveDefault(projectId),
     log,
   });
-
-  // Mark any active pipeline states as interrupted (server restart recovery)
-  pipelineStateStore.markInterrupted().catch((err: any) => {
-    log('STARTUP', `Failed to mark interrupted pipelines: ${err.message}`);
-  });
 };

package/templates/assistkick-product-system/packages/backend/src/services/project_service.test.ts

@@ -118,12 +118,28 @@ describe('ProjectService', () => {
 
       assert.ok(result.id.startsWith('proj_'));
       assert.equal(result.name, 'New Project');
+      assert.equal(result.type, 'software');
       assert.equal(result.isDefault, 0);
       assert.equal(result.archivedAt, null);
       assert.ok(result.createdAt);
       assert.ok(result.updatedAt);
       assert.equal(db.insert.mock.calls.length, 1);
     });
+
+    it('creates a project with video type', async () => {
+      const result = await service.create('Video Project', 'video');
+
+      assert.ok(result.id.startsWith('proj_'));
+      assert.equal(result.name, 'Video Project');
+      assert.equal(result.type, 'video');
+      assert.equal(result.isDefault, 0);
+    });
+
+    it('defaults to software type when no type specified', async () => {
+      const result = await service.create('Default Type');
+
+      assert.equal(result.type, 'software');
+    });
   });
 
   describe('rename', () => {

package/templates/assistkick-product-system/packages/backend/src/services/project_service.ts

@@ -15,12 +15,16 @@ interface ProjectServiceDeps {
 export interface ProjectRecord {
   id: string;
   name: string;
+  type: string;
   isDefault: number;
   archivedAt: string | null;
   repoUrl: string | null;
   githubInstallationId: string | null;
   githubRepoFullName: string | null;
   baseBranch: string | null;
+  gitAuthMethod: string | null;
+  sshPrivateKeyEncrypted: string | null;
+  sshPublicKey: string | null;
   createdAt: string;
   updatedAt: string;
 }
@@ -58,7 +62,7 @@ export class ProjectService {
     return row || null;
   };
 
-  create = async (name: string): Promise<ProjectRecord> => {
+  create = async (name: string, type: string = 'software'): Promise<ProjectRecord> => {
     const db = this.getDb();
     const now = new Date().toISOString();
     const id = this.generateId();
@@ -66,18 +70,22 @@ export class ProjectService {
     const record: ProjectRecord = {
       id,
       name,
+      type,
       isDefault: 0,
       archivedAt: null,
       repoUrl: null,
       githubInstallationId: null,
       githubRepoFullName: null,
       baseBranch: null,
+      gitAuthMethod: null,
+      sshPrivateKeyEncrypted: null,
+      sshPublicKey: null,
       createdAt: now,
       updatedAt: now,
     };
 
     await db.insert(projects).values(record);
-    this.log('PROJECTS', `Created project: ${name} (${id})`);
+    this.log('PROJECTS', `Created project: ${name} (${id}) type=${type}`);
     return record;
   };
 
@@ -195,6 +203,9 @@ export class ProjectService {
         githubInstallationId: null,
         githubRepoFullName: null,
         baseBranch: null,
+        gitAuthMethod: null,
+        sshPrivateKeyEncrypted: null,
+        sshPublicKey: null,
         updatedAt: now,
       })
       .where(eq(projects.id, id));
@@ -206,6 +217,66 @@ export class ProjectService {
       githubInstallationId: null,
       githubRepoFullName: null,
       baseBranch: null,
+      gitAuthMethod: null,
+      sshPrivateKeyEncrypted: null,
+      sshPublicKey: null,
+      updatedAt: now,
+    };
+  };
+
+  /** Store SSH key data and set auth method to 'ssh_key'. */
+  setSshKeys = async (id: string, opts: {
+    sshPrivateKeyEncrypted: string;
+    sshPublicKey: string;
+  }): Promise<ProjectRecord> => {
+    const db = this.getDb();
+    const existing = await this.getById(id);
+    if (!existing) throw new Error('Project not found');
+
+    const now = new Date().toISOString();
+    await db
+      .update(projects)
+      .set({
+        gitAuthMethod: 'ssh_key',
+        sshPrivateKeyEncrypted: opts.sshPrivateKeyEncrypted,
+        sshPublicKey: opts.sshPublicKey,
+        updatedAt: now,
+      })
+      .where(eq(projects.id, id));
+
+    this.log('PROJECTS', `Set SSH keys for project ${id}`);
+    return {
+      ...existing,
+      gitAuthMethod: 'ssh_key',
+      sshPrivateKeyEncrypted: opts.sshPrivateKeyEncrypted,
+      sshPublicKey: opts.sshPublicKey,
+      updatedAt: now,
+    };
+  };
+
+  /** Set auth method to 'github_app' and clear SSH keys. */
+  setGitHubAppAuth = async (id: string): Promise<ProjectRecord> => {
+    const db = this.getDb();
+    const existing = await this.getById(id);
+    if (!existing) throw new Error('Project not found');
+
+    const now = new Date().toISOString();
+    await db
+      .update(projects)
+      .set({
+        gitAuthMethod: 'github_app',
+        sshPrivateKeyEncrypted: null,
+        sshPublicKey: null,
+        updatedAt: now,
+      })
+      .where(eq(projects.id, id));
+
+    this.log('PROJECTS', `Set GitHub App auth for project ${id}`);
+    return {
+      ...existing,
+      gitAuthMethod: 'github_app',
+      sshPrivateKeyEncrypted: null,
+      sshPublicKey: null,
       updatedAt: now,
     };
   };

package/templates/assistkick-product-system/packages/backend/src/services/project_workspace_service.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { ProjectWorkspaceService } from './project_workspace_service.ts';
 import { join } from 'node:path';
 
-const PROJECT_ROOT = '/tmp/test-project-root';
+const WORKSPACES_DIR = '/tmp/test-workspaces';
 
 const createMockClaudeService = () => ({
   spawnCommand: mock.fn(async () => ''),
@@ -12,7 +12,7 @@ const createMockClaudeService = () => ({
 const createService = (claudeService: any) => {
   return new ProjectWorkspaceService({
     claudeService,
-    projectRoot: PROJECT_ROOT,
+    workspacesDir: WORKSPACES_DIR,
     log: mock.fn(),
   });
 };
@@ -29,14 +29,14 @@ describe('ProjectWorkspaceService', () => {
   describe('getWorkspacePath', () => {
     it('returns correct workspace path for a project', () => {
       const path = service.getWorkspacePath('proj_abc123');
-      assert.equal(path, join(PROJECT_ROOT, 'workspaces', 'proj_abc123'));
+      assert.equal(path, join(WORKSPACES_DIR, 'proj_abc123'));
     });
   });
 
   describe('getWorktreesDir', () => {
     it('returns correct worktrees dir inside workspace', () => {
       const path = service.getWorktreesDir('proj_abc123');
-      assert.equal(path, join(PROJECT_ROOT, 'workspaces', 'proj_abc123', '.worktrees'));
+      assert.equal(path, join(WORKSPACES_DIR, 'proj_abc123', '.worktrees'));
     });
   });
 

package/templates/assistkick-product-system/packages/backend/src/services/project_workspace_service.ts

@@ -1,6 +1,8 @@
 /**
  * ProjectWorkspaceService — manages per-project workspace directories.
- * Each project gets a workspace at <projectRoot>/workspaces/<projectId>/.
+ * Each project gets a workspace at <workspacesDir>/<projectId>/.
+ * workspacesDir is injected via DI — in production it resolves to a persistent
+ * volume (/data/workspaces), in development to <projectRoot>/workspaces.
  * If a remote git repo is connected, it is cloned there.
  * If not, git init creates a local repo so worktrees and branching always work.
  */
@@ -8,27 +10,31 @@
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
+import type { SshKeyService } from './ssh_key_service.js';
 
 interface ProjectWorkspaceServiceDeps {
-  claudeService: { spawnCommand: (cmd: string, args: string[], cwd: string) => Promise<string> };
-  projectRoot: string;
+  claudeService: { spawnCommand: (cmd: string, args: string[], cwd: string, env?: Record<string, string>) => Promise<string> };
+  workspacesDir: string;
   log: (tag: string, ...args: any[]) => void;
+  sshKeyService?: SshKeyService;
 }
 
 export class ProjectWorkspaceService {
   private readonly claudeService: ProjectWorkspaceServiceDeps['claudeService'];
-  private readonly projectRoot: string;
+  private readonly workspacesDir: string;
   private readonly log: ProjectWorkspaceServiceDeps['log'];
+  private readonly sshKeyService?: SshKeyService;
 
-  constructor({ claudeService, projectRoot, log }: ProjectWorkspaceServiceDeps) {
+  constructor({ claudeService, workspacesDir, log, sshKeyService }: ProjectWorkspaceServiceDeps) {
     this.claudeService = claudeService;
-    this.projectRoot = projectRoot;
+    this.workspacesDir = workspacesDir;
     this.log = log;
+    this.sshKeyService = sshKeyService;
   }
 
   /** Get the workspace directory path for a project. */
   getWorkspacePath = (projectId: string): string => {
-    return join(this.projectRoot, 'workspaces', projectId);
+    return join(this.workspacesDir, projectId);
   };
 
   /** Get the worktrees directory inside a project workspace. */
@@ -71,17 +77,16 @@ export class ProjectWorkspaceService {
   /** Clone a remote repository into the project workspace. */
   cloneRepo = async (projectId: string, cloneUrl: string): Promise<string> => {
     const wsPath = this.getWorkspacePath(projectId);
-    const parentDir = join(this.projectRoot, 'workspaces');
-    await this.ensureDir(parentDir);
+    await this.ensureDir(this.workspacesDir);
 
     // If workspace already exists, remove it first
     if (existsSync(wsPath)) {
       this.log('WORKSPACE', `Removing existing workspace before clone: ${wsPath}`);
-      await this.claudeService.spawnCommand('rm', ['-rf', wsPath], parentDir);
+      await this.claudeService.spawnCommand('rm', ['-rf', wsPath], this.workspacesDir);
     }
 
     this.log('WORKSPACE', `Cloning ${cloneUrl} into ${wsPath}`);
-    await this.claudeService.spawnCommand('git', ['clone', cloneUrl, wsPath], parentDir);
+    await this.claudeService.spawnCommand('git', ['clone', cloneUrl, wsPath], this.workspacesDir);
     this.log('WORKSPACE', `Clone completed for project ${projectId}`);
     return wsPath;
   };
@@ -162,6 +167,77 @@ export class ProjectWorkspaceService {
     }
   };
 
+  /**
+   * Run a git command with GIT_SSH_COMMAND set for SSH key auth.
+   * Handles writing temp key, setting env, running the command, and cleanup.
+   */
+  private withSshKey = async <T>(encryptedPrivateKey: string, fn: () => Promise<T>): Promise<T> => {
+    if (!this.sshKeyService) throw new Error('SshKeyService not available');
+
+    const privateKeyPem = this.sshKeyService.decrypt(encryptedPrivateKey);
+    const keyFilePath = await this.sshKeyService.writeTempKeyFile(privateKeyPem);
+    const gitSshCommand = this.sshKeyService.buildGitSshCommand(keyFilePath);
+    const previousValue = process.env.GIT_SSH_COMMAND;
+
+    process.env.GIT_SSH_COMMAND = gitSshCommand;
+    try {
+      return await fn();
+    } finally {
+      if (previousValue !== undefined) {
+        process.env.GIT_SSH_COMMAND = previousValue;
+      } else {
+        delete process.env.GIT_SSH_COMMAND;
+      }
+      await this.sshKeyService.removeTempKeyFile(keyFilePath);
+    }
+  };
+
+  /** Clone a remote repository using SSH key authentication. */
+  cloneRepoSsh = async (projectId: string, sshCloneUrl: string, encryptedPrivateKey: string): Promise<string> => {
+    const wsPath = this.getWorkspacePath(projectId);
+    await this.ensureDir(this.workspacesDir);
+
+    if (existsSync(wsPath)) {
+      this.log('WORKSPACE', `Removing existing workspace before SSH clone: ${wsPath}`);
+      await this.claudeService.spawnCommand('rm', ['-rf', wsPath], this.workspacesDir);
+    }
+
+    this.log('WORKSPACE', `SSH cloning into ${wsPath}`);
+    await this.withSshKey(encryptedPrivateKey, () =>
+      this.claudeService.spawnCommand('git', ['clone', sshCloneUrl, wsPath], this.workspacesDir),
+    );
+    this.log('WORKSPACE', `SSH clone completed for project ${projectId}`);
+    return wsPath;
+  };
+
+  /** Pull latest changes using SSH key authentication. */
+  pullLatestSsh = async (projectId: string, encryptedPrivateKey: string): Promise<void> => {
+    const wsPath = this.getWorkspacePath(projectId);
+
+    try {
+      const branch = await this.getDefaultBranch(projectId);
+      this.log('WORKSPACE', `SSH pulling latest on ${branch} for project ${projectId}`);
+      await this.withSshKey(encryptedPrivateKey, () =>
+        this.claudeService.spawnCommand('git', ['pull', 'origin', branch], wsPath),
+      );
+      this.log('WORKSPACE', `SSH pull completed for project ${projectId}`);
+    } catch (err: any) {
+      this.log('WORKSPACE', `SSH pull failed (non-fatal): ${err.message}`);
+    }
+  };
+
+  /** Push the default branch to the remote using SSH key authentication. */
+  pushToRemoteSsh = async (projectId: string, encryptedPrivateKey: string): Promise<void> => {
+    const wsPath = this.getWorkspacePath(projectId);
+    const branch = await this.getDefaultBranch(projectId);
+
+    this.log('WORKSPACE', `SSH pushing ${branch} to remote for project ${projectId}`);
+    await this.withSshKey(encryptedPrivateKey, () =>
+      this.claudeService.spawnCommand('git', ['push', 'origin', branch], wsPath),
+    );
+    this.log('WORKSPACE', `SSH push completed for project ${projectId}`);
+  };
+
   /** Get workspace git status info. */
   getStatus = async (projectId: string): Promise<{
     hasWorkspace: boolean;