@goodandready/dsh-kanban 0.2.19 → 0.2.20

package/lib/worktree.js

@@ -1,15 +1,15 @@
-// Управляемые воркдеревья для сессий агентов под задачи (Issue #193).
+// Managed worktrees for task agent sessions (Issue #193).
 //
-// Изоляция сессии агента в отдельном git worktree защищает основной
-// репозиторий от параллельных правок нескольких задач, предотвращает
-// перезапись веток и фиксирует рабочее окружение карточки.
+// Isolating agent sessions in git worktrees protects the main repository
+// from concurrent modifications, prevents branch overwrite conflicts,
+// and scopes working directory per task.
 //
-// Жизненный цикл:
-// 1. При переходе в In Progress создаётся воркдерево task/<id>-<slug>
-// 2. Воркдерево регистрируется в DSH workspaceRegistry как рабочий каталог
-// 3. Сессия агента запускается с cwd = worktreePath
-// 4. В колонке Cleanup проверяются незакоммиченные файлы (dirtyFiles)
-// 5. После подтверждения воркдерево удаляется, воркспейс дерегистрируется.
+// Lifecycle:
+// 1. On transition to In Progress: create worktree task/<id>-<slug>
+// 2. Register worktree in DSH workspaceRegistry as active workspace
+// 3. Launch agent session with cwd = worktreePath
+// 4. In Cleanup column: verify uncommitted files (dirtyFiles)
+// 5. Upon confirmation: remove worktree and deregister workspace.
 
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
@@ -20,8 +20,8 @@ import { isAbsolute, join, resolve, sep } from 'node:path'
 const execFileAsync = promisify(execFile)
 
 /**
- * Стандартный исполнитель git-команд.
- * Принимает аргументы массивом, исключая шелл-инъекции.
+ * Standard git command runner.
+ * Accepts argument array to eliminate shell injection vulnerabilities.
  */
 export async function defaultGitRunner(args, cwd) {
   try {
@@ -41,7 +41,7 @@ export async function defaultGitRunner(args, cwd) {
 }
 
 /**
- * Преобразовать строку в безопасный фрагмент имени ветки или каталога.
+ * Convert string into safe branch/directory slug.
  */
 export function slugify(text) {
   if (typeof text !== 'string') return 'task'
@@ -49,7 +49,7 @@ export function slugify(text) {
     .toLowerCase()
     .normalize('NFD')
     .replace(/[\u0300-\u036f]/g, '')
-    .replace(/[^a-z0-9а-яё_-]+/gi, '-')
+    .replace(/[^\p{Letter}0-9_-]+/gu, '-')
     .replace(/-+/g, '-')
     .replace(/^-|-$/g, '')
     .slice(0, 40)
@@ -57,7 +57,7 @@ export function slugify(text) {
 }
 
 /**
- * Безопасный ключ репозитория для каталога воркдеревьев.
+ * Safe repository key for worktree root directory.
  */
 export function safeRepoKey(task) {
   const owner = typeof task?.owner === 'string' ? task.owner.trim() : ''
@@ -68,7 +68,7 @@ export function safeRepoKey(task) {
 }
 
 /**
- * Определить корневой каталог для всех управляемых воркдеревьев.
+ * Resolve root directory for all managed worktrees.
  */
 export function resolveWorktreeRoot(config, env = process.env, cwdOf = () => process.cwd()) {
   const custom = typeof config?.worktreeRoot === 'string' ? config.worktreeRoot.trim() : ''
@@ -85,7 +85,7 @@ export function resolveWorktreeRoot(config, env = process.env, cwdOf = () => pro
 }
 
 /**
- * Вычислить канонический путь к воркдереву задачи с защитой от path traversal.
+ * Resolve canonical worktree path for task with path traversal protection.
  */
 export function resolveTaskWorktreePath({ task, config, env, cwdOf }) {
   const root = resolveWorktreeRoot(config, env, cwdOf)
@@ -95,13 +95,13 @@ export function resolveTaskWorktreePath({ task, config, env, cwdOf }) {
 
   const fenceSep = root.endsWith(sep) || root.endsWith('/') ? root : root + sep
   if (target !== root && !target.startsWith(fenceSep) && !target.startsWith(root + '/')) {
-    throw new Error('путь воркдерева выходит за пределы корня воркдеревьев')
+    throw new Error('worktree path escapes worktree root')
   }
   return target
 }
 
 /**
- * Сформировать имя ветки задачи.
+ * Generate task branch name.
  */
 export function resolveTaskBranch(task) {
   const prefix = typeof task?.issueNumber === 'number'
@@ -112,7 +112,7 @@ export function resolveTaskBranch(task) {
 }
 
 /**
- * Проверить, является ли каталог git-репозиторием.
+ * Check if directory is a valid git repository.
  */
 export async function isGitRepo(repoDir, gitRunner = defaultGitRunner) {
   if (!repoDir) return false
@@ -125,7 +125,7 @@ export async function isGitRepo(repoDir, gitRunner = defaultGitRunner) {
 }
 
 /**
- * Получить список существующих путей воркдеревьев для репозитория.
+ * List existing worktree paths for repository.
  */
 export async function listWorktrees(repoDir, gitRunner = defaultGitRunner) {
   try {
@@ -143,7 +143,7 @@ export async function listWorktrees(repoDir, gitRunner = defaultGitRunner) {
 }
 
 /**
- * Определить базовую ветку для создания воркдерева.
+ * Resolve base ref for worktree creation.
  */
 export async function determineBaseRef(repoDir, gitRunner = defaultGitRunner) {
   for (const candidate of ['origin/main', 'origin/master', 'main', 'master', 'HEAD']) {
@@ -158,7 +158,7 @@ export async function determineBaseRef(repoDir, gitRunner = defaultGitRunner) {
 }
 
 /**
- * Создать или переиспользовать воркдерево под задачу.
+ * Create or reuse worktree for task.
  */
 export async function createTaskWorktree({
   task,
@@ -180,13 +180,13 @@ export async function createTaskWorktree({
   const worktreePath = resolveTaskWorktreePath({ task, config, env, cwdOf })
   const branchName = resolveTaskBranch(task)
 
-  // Проверяем, не зарегистрировано ли уже это воркдерево
+  // Check if worktree is already registered
   const existing = await listWorktrees(repoDir, gitRunner)
   if (existing.includes(resolve(worktreePath))) {
     return { worktreePath, branchName, reused: true }
   }
 
-  // Проверяем, существует ли уже локальная ветка с таким именем
+  // Check if local branch already exists
   let branchExists = false
   try {
     await gitRunner(['rev-parse', '--verify', '--quiet', `refs/heads/${branchName}`], repoDir)
@@ -206,7 +206,7 @@ export async function createTaskWorktree({
 }
 
 /**
- * Проверить наличие незакоммиченных изменений в воркдереве.
+ * Check for uncommitted changes in worktree.
  */
 function isSubmoduleDrift(worktreePath, line) {
   try {
@@ -226,14 +226,14 @@ function isSubmoduleDrift(worktreePath, line) {
       }
     }
   } catch {
-    // Игнорируем ошибки доступа к файлам при проверке
+    // Ignore file access errors during check
   }
   return false
 }
 
 /**
- * Проверить наличие незакоммиченных изменений в воркдереве.
- * Исключает структурный шум субмодулей и дрейф gitlinks (#213).
+ * Check for uncommitted changes in worktree.
+ * Excludes submodule noise and gitlink drift (#213).
  */
 export async function checkWorktreeDirty({ worktreePath, gitRunner = defaultGitRunner }) {
   if (!worktreePath || !existsSync(worktreePath)) {
@@ -253,7 +253,7 @@ export async function checkWorktreeDirty({ worktreePath, gitRunner = defaultGitR
 }
 
 /**
- * Безопасно удалить воркдерево задачи.
+ * Safely remove task worktree.
  */
 export async function removeTaskWorktree({
   repoDir,
@@ -281,7 +281,7 @@ export async function removeTaskWorktree({
     : ['worktree', 'remove', worktreePath]
 
   await gitRunner(removeArgs, repoDir)
-  try { await gitRunner(['worktree', 'prune'], repoDir) } catch { /* prune игнорирует ошибки */ }
+  try { await gitRunner(['worktree', 'prune'], repoDir) } catch { /* prune ignores errors */ }
 
   let branchDeleted = false
   if (deleteBranch && branchName && repoDir) {
@@ -289,7 +289,7 @@ export async function removeTaskWorktree({
       await gitRunner(['branch', '-d', branchName], repoDir)
       branchDeleted = true
     } catch {
-      // Игнорируем: ветка не удалена, если ещё не влита
+      // Ignored: branch not deleted if not yet merged
       branchDeleted = false
     }
   }
@@ -298,7 +298,7 @@ export async function removeTaskWorktree({
 }
 
 /**
- * Зарегистрировать каталог воркдерева в DSH workspaceRegistry.
+ * Register worktree path in DSH workspaceRegistry.
  */
 export async function registerDshWorkspace({ workspaceRegistry, worktreePath, title }) {
   if (!workspaceRegistry || typeof workspaceRegistry.create !== 'function') return undefined
@@ -311,7 +311,7 @@ export async function registerDshWorkspace({ workspaceRegistry, worktreePath, ti
 }
 
 /**
- * Дерегистрировать воркспейс из DSH workspaceRegistry.
+ * Deregister workspace from DSH workspaceRegistry.
  */
 export async function deregisterDshWorkspace({ workspaceRegistry, workspaceId }) {
   if (!workspaceRegistry || typeof workspaceRegistry.delete !== 'function' || !workspaceId) return false
@@ -323,7 +323,7 @@ export async function deregisterDshWorkspace({ workspaceRegistry, workspaceId })
 }
 
 /**
- * Выполнить очистку воркдерева задачи с проверкой незакоммиченных изменений.
+ * Clean up task worktree with dirty files guard.
  */
 export async function cleanupTaskWorktree({
   store,
@@ -354,7 +354,7 @@ export async function cleanupTaskWorktree({
       fromCol: current.column,
       toCol: current.column,
       source: 'session',
-      detail: `очистка отложена: обнаружены незакоммиченные файлы: ${result.files.slice(0, 3).join(', ')}`,
+      detail: `cleanup deferred: uncommitted files detected: ${result.files.slice(0, 3).join(', ')}`,
     })
     return { error: 'worktree-dirty', files: result.files }
   }
@@ -369,14 +369,14 @@ export async function cleanupTaskWorktree({
     fromCol: current.column,
     toCol: current.column,
     source: 'session',
-    detail: 'очистка: воркдерево удалено' + (result.branchDeleted ? ', ветка удалена' : ''),
+    detail: 'cleanup: worktree removed' + (result.branchDeleted ? ', branch deleted' : ''),
   })
 
   return { success: true, removed: true, branchDeleted: result.branchDeleted }
 }
 
 /**
- * Получить unified diff изменений в воркдереве задачи (#211).
+ * Generate unified diff of changes in task worktree (#211).
  *
  * @param {{worktreePath: string, baseRef?: string, gitRunner?: Function}} options
  * @returns {Promise<{diff: string, truncated: boolean, filesChanged: number}>}
@@ -391,7 +391,7 @@ export async function getTaskDiff({ worktreePath, baseRef, gitRunner = defaultGi
     base = await determineBaseRef(worktreePath, gitRunner)
   }
 
-  // Сначала пробуем git diff base...HEAD, если base доступен
+  // Try git diff base...HEAD first if base ref is available
   let diffOut = ''
   if (base) {
     const res = await gitRunner(['diff', `${base}...HEAD`], worktreePath)
@@ -400,23 +400,23 @@ export async function getTaskDiff({ worktreePath, baseRef, gitRunner = defaultGi
     }
   }
 
-  // Дополнительно смотрим незакоммиченные изменения (unstaged + staged)
+  // Include uncommitted changes (unstaged + staged)
   const unstaged = await gitRunner(['diff', 'HEAD'], worktreePath)
   if (unstaged.exitCode === 0 && unstaged.stdout.trim() !== '') {
     diffOut = diffOut ? `${diffOut}\n\n# Uncommitted Changes:\n${unstaged.stdout}` : unstaged.stdout
   }
 
-  // Если и base...HEAD, и HEAD ничего не дали, берём чистый git diff
+  // Fallback to plain git diff if base...HEAD produced no output
   if (!diffOut.trim()) {
     const fallback = await gitRunner(['diff'], worktreePath)
     if (fallback.exitCode === 0) diffOut = fallback.stdout
   }
 
-  // Подсчитываем число затронутых файлов
+  // Count affected files
   const fileLines = diffOut.split('\n').filter((l) => l.startsWith('diff --git'))
   const filesChanged = fileLines.length
 
-  // Защита от переполнения: обрезаем diff до 250 КБ
+  // Memory guard: cap diff output at 250 KiB
   const MAX_DIFF_BYTES = 250 * 1024
   let truncated = false
   if (Buffer.byteLength(diffOut, 'utf8') > MAX_DIFF_BYTES) {
@@ -428,7 +428,7 @@ export async function getTaskDiff({ worktreePath, baseRef, gitRunner = defaultGi
 }
 
 /**
- * Получить список коммитов ветки задачи относительно базовой ветки (#211).
+ * List task branch commits relative to base branch (#211).
  *
  * @param {{worktreePath: string, baseRef?: string, gitRunner?: Function}} options
  * @returns {Promise<Array<{hash: string, subject: string, author: string, date: string}>>}
@@ -446,7 +446,7 @@ export async function getTaskCommits({ worktreePath, baseRef, gitRunner = defaul
   const range = base ? `${base}..HEAD` : '-n 20'
   const logRes = await gitRunner(['log', range, '--pretty=format:%h%x09%an%x09%ad%x09%s', '--date=short'], worktreePath)
   if (logRes.exitCode !== 0 || !logRes.stdout.trim()) {
-    // fallback на последние 10 коммитов
+    // Fallback to last 10 commits
     const fallback = await gitRunner(['log', '-n', '10', '--pretty=format:%h%x09%an%x09%ad%x09%s', '--date=short'], worktreePath)
     if (fallback.exitCode !== 0 || !fallback.stdout.trim()) return []
     return fallback.stdout.trim().split('\n').map(parseCommitLine).filter(Boolean)
@@ -467,7 +467,7 @@ function parseCommitLine(line) {
 }
 
 /**
- * Слияние ветки воркдерева в основную ветку репозитория (--no-ff) при приёмке (#212).
+ * Merge worktree branch into repository main branch (--no-ff) upon acceptance (#212).
  *
  * @param {{task: object, targetBranch?: string, gitRunner?: Function, workspaceRegistry?: object}} options
  * @returns {Promise<{success: boolean, merged: boolean, error?: string}>}
@@ -479,13 +479,13 @@ export async function mergeTaskWorktree({
     return { success: false, merged: false, error: 'no-worktree-or-branch' }
   }
 
-  // 1. Проверяем чистоту воркдерева
+  // 1. Verify worktree cleanliness
   const dirtyCheck = await checkWorktreeDirty({ worktreePath: task.worktree, gitRunner })
   if (dirtyCheck.dirty) {
     return { success: false, merged: false, error: 'worktree-dirty', files: dirtyCheck.files }
   }
 
-  // 2. Находим корень основного репозитория (из .git файла воркдерева или config)
+  // 2. Locate main repository root
   let mainRepoDir = ''
   const revParse = await gitRunner(['rev-parse', '--git-common-dir'], task.worktree)
   if (revParse.exitCode === 0 && revParse.stdout.trim()) {
@@ -497,14 +497,14 @@ export async function mergeTaskWorktree({
     return { success: false, merged: false, error: 'main-repo-not-found' }
   }
 
-  // 3. Определяем целевую ветку для слияния
+  // 3. Resolve target merge branch
   let target = targetBranch
   if (!target) {
     target = await determineBaseRef(mainRepoDir, gitRunner)
   }
   if (!target) target = 'main'
 
-  // 4. Переключаемся или проверяем, что в целевой ветке в основном репо
+  // 4. Switch or verify target branch in main repository
   const currentBranch = await gitRunner(['branch', '--show-current'], mainRepoDir)
   if (currentBranch.stdout.trim() !== target) {
     const checkoutRes = await gitRunner(['checkout', target], mainRepoDir)
@@ -513,16 +513,16 @@ export async function mergeTaskWorktree({
     }
   }
 
-  // 5. Выполняем git merge --no-ff
+  // 5. Execute git merge --no-ff
   const mergeMsg = `Merge branch '${task.branch}' for task ${task.id}`
   const mergeRes = await gitRunner(['merge', '--no-ff', task.branch, '-m', mergeMsg], mainRepoDir)
   if (mergeRes.exitCode !== 0) {
-    // В случае конфликта откатываем мерж
+    // Roll back merge on conflict
     await gitRunner(['merge', '--abort'], mainRepoDir)
     return { success: false, merged: false, error: 'merge-conflict', detail: mergeRes.stderr || mergeRes.stdout }
   }
 
-  // 6. Очищаем воркдерево задачи
+  // 6. Clean up task worktree
   await cleanupTaskWorktree({
     task,
     workspaceRegistry,
@@ -535,9 +535,9 @@ export async function mergeTaskWorktree({
 
 
 /**
- * Рекурсивное обнаружение всех git-репозиториев в каталоге воркспейса (#210).
+ * Recursive discovery of git repositories within workspace directory (#210).
  *
- * @param {string} rootDir Корневой каталог для поиска
+ * @param {string} rootDir Root directory to scan
  * @param {{maxDepth?: number, maxRepos?: number, gitRunner?: Function}} options
  * @returns {Promise<Array<{relPath: string, fullPath: string, name: string}>>}
  */
@@ -561,7 +561,7 @@ export async function findWorkspaceGitRepos(rootDir, options = {}) {
           fullPath: resolve(dir),
           name: basename(resolve(dir)),
         })
-        // Если это репозиторий (не root), глубже в него обычно не сканируем (кроме субмодулей если нужно)
+        // Do not recurse into nested non-root repositories
         if (depth > 0) return
       }
 
@@ -572,7 +572,7 @@ export async function findWorkspaceGitRepos(rootDir, options = {}) {
         await scan(join(dir, entry.name), depth + 1)
       }
     } catch {
-      // Игнорируем недоступные директории
+      // Ignore inaccessible directories
     }
   }
 
@@ -581,7 +581,7 @@ export async function findWorkspaceGitRepos(rootDir, options = {}) {
 }
 
 /**
- * Подготовка мультирепозиторного зеркалирования для воркспейса с несколькими git-репозиториями (#210).
+ * Multi-repository mirror setup for workspaces with multiple git repositories (#210).
  *
  * @param {{task: object, workspacePath: string, gitRunner?: Function, config?: object}} options
  * @returns {Promise<{mirrors: Array<{repo: string, worktreePath: string, branch: string}>, errors?: Array<string>}>}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-kanban",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "Visual Kanban board for DeepSeek Harness: Gitea and GitHub-backed tasks, workflow columns, and a dedicated agent session per task.",
   "type": "module",
   "main": "lib/index.js",