@loicngr/kobo 1.4.5 → 1.4.7

package/dist/server/services/notion-service.js

@@ -3,7 +3,6 @@ import { readFileSync } from 'node:fs';
 import { getPackageVersion } from '../utils/paths.js';
 // Gherkin keywords (French and English)
 const GHERKIN_PATTERN = /^(Scénario|Étant donné|Quand|Alors|Scenario|Given|When|Then|Feature|Fonctionnalité|And|Et|But|Mais)/i;
-// C2: rpcIdCounter encapsulated in a closure to avoid module-level mutable state
 const nextRpcId = (() => {
     let counter = 1;
     return () => counter++;
@@ -32,11 +31,7 @@ export function parseNotionUrl(url) {
     // Convert 32 hex chars to UUID format: 8-4-4-4-12
     return `${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20)}`;
 }
-/**
- * Send a JSON-RPC request to the MCP process and read the response.
- * M4: parameter renamed from `process` to `mcpProcess` to avoid shadowing global `process`.
- * C1: 30s timeout added to prevent hanging indefinitely.
- */
+/** Send a JSON-RPC request to the MCP process and read the response (30s timeout). */
 export async function callMcpTool(mcpProcess, toolName, args) {
     const id = nextRpcId();
     const request = JSON.stringify({
@@ -54,7 +49,6 @@ export async function callMcpTool(mcpProcess, toolName, args) {
             return;
         }
         let buffer = '';
-        // C1: 30s timeout — I7: kill the MCP process on timeout to avoid zombie
         const timeout = setTimeout(() => {
             mcpProcess.stdout?.removeListener('data', onData);
             mcpProcess.stdout?.removeListener('error', onError);
@@ -142,12 +136,7 @@ function spawnMcpProcess() {
     });
     return mcpProcess;
 }
-/**
- * Initialize the MCP server by sending an initialize request.
- * I1: notifications/initialized is sent after receiving the initialize response.
- * I4: onData listener is removed in the reject path.
- * C1: 10s timeout added.
- */
+/** Initialize the MCP server by sending an initialize handshake (10s timeout). */
 async function initializeMcp(mcpProcess) {
     const id = nextRpcId();
     const request = JSON.stringify({
@@ -166,7 +155,6 @@ async function initializeMcp(mcpProcess) {
             return;
         }
         let buffer = '';
-        // C1: 10s timeout for initialization — I7: kill the MCP process on timeout
         const timeout = setTimeout(() => {
             mcpProcess.stdout?.removeListener('data', onData);
             mcpProcess.kill();
@@ -185,7 +173,6 @@ async function initializeMcp(mcpProcess) {
                     if (parsed.id === id) {
                         clearTimeout(timeout);
                         mcpProcess.stdout?.removeListener('data', onData);
-                        // I1: Send notifications/initialized AFTER receiving the initialize response
                         const initialized = JSON.stringify({
                             jsonrpc: '2.0',
                             method: 'notifications/initialized',
@@ -199,7 +186,6 @@ async function initializeMcp(mcpProcess) {
                 }
             }
         };
-        // I4: onError handler to clean up listener on error
         const onError = (err) => {
             clearTimeout(timeout);
             mcpProcess.stdout?.removeListener('data', onData);
@@ -244,6 +230,7 @@ function extractTextFromRichText(richText) {
     })
         .join('');
 }
+/** Parse Notion block children into structured goal, todos, and Gherkin features. */
 export function parseBlocks(blocks) {
     const todos = [];
     const gherkinFeatures = [];
@@ -336,6 +323,7 @@ export async function extractNotionPage(notionUrl) {
         const pageRaw = await callMcpTool(mcpProcess, 'API-retrieve-a-page', { page_id: pageId });
         const pageResult = unwrapMcpResult(pageRaw);
         let title = '';
+        let ticketId = '';
         if (pageResult && typeof pageResult === 'object') {
             const result = pageResult;
             const properties = result.properties;
@@ -344,7 +332,15 @@ export async function extractNotionPage(notionUrl) {
                     const propObj = prop;
                     if (propObj.type === 'title' && Array.isArray(propObj.title)) {
                         title = extractTextFromRichText(propObj.title);
-                        break;
+                    }
+                    // Extract unique_id (e.g., "TK-1120") from Notion database properties
+                    if (propObj.type === 'unique_id' && propObj.unique_id) {
+                        const uid = propObj.unique_id;
+                        const prefix = uid.prefix ?? '';
+                        const number = uid.number;
+                        if (number !== undefined) {
+                            ticketId = prefix ? `${prefix}-${number}` : String(number);
+                        }
                     }
                 }
             }
@@ -362,7 +358,7 @@ export async function extractNotionPage(notionUrl) {
             }
         }
         const { goal, todos, gherkinFeatures } = parseBlocks(blocks);
-        return { title, goal, todos, gherkinFeatures };
+        return { title, ticketId, goal, todos, gherkinFeatures };
     }
     finally {
         // Ensure the MCP process is terminated

package/dist/server/services/pr-watcher-service.js

@@ -69,11 +69,13 @@ function scheduleNext() {
     }, POLL_INTERVAL_MS);
     timer.unref?.();
 }
+/** Start polling GitHub for merged/closed PRs to auto-archive workspaces. */
 export function startPrWatcher() {
     if (timer)
         return;
     scheduleNext();
 }
+/** Stop the PR watcher polling loop. */
 export function stopPrWatcher() {
     if (timer) {
         clearTimeout(timer);

package/dist/server/services/settings-service.js

@@ -89,6 +89,18 @@ const settingsMigrations = [
             }
         },
     },
+    {
+        version: 4,
+        name: 'add-editor-and-notifications',
+        migrate({ global }) {
+            if (typeof global.editorCommand !== 'string')
+                global.editorCommand = '';
+            if (typeof global.browserNotifications !== 'boolean')
+                global.browserNotifications = true;
+            if (typeof global.audioNotifications !== 'boolean')
+                global.audioNotifications = true;
+        },
+    },
 ];
 /** Current settings schema version — always equals the highest migration version. */
 export const SETTINGS_SCHEMA_VERSION = settingsMigrations.length > 0 ? settingsMigrations[settingsMigrations.length - 1].version : 0;
@@ -105,6 +117,9 @@ function defaultSettings() {
             dangerouslySkipPermissions: true,
             prPromptTemplate: DEFAULT_PR_PROMPT_TEMPLATE,
             gitConventions: DEFAULT_GIT_CONVENTIONS,
+            editorCommand: '',
+            browserNotifications: true,
+            audioNotifications: true,
         },
         projects: [],
     };
@@ -128,11 +143,7 @@ function defaultProjectSettings(projectPath) {
 function pickKnownKeys(data, allowedKeys) {
     return Object.fromEntries(Object.entries(data).filter(([key]) => allowedKeys.includes(key)));
 }
-/**
- * Apply migrations sequentially to bring an older settings object up to
- * SETTINGS_SCHEMA_VERSION. Append-only — never edit or reorder shipped entries.
- * The returned object carries the bumped schemaVersion; callers persist it.
- */
+/** Apply settings migrations sequentially up to SETTINGS_SCHEMA_VERSION. Append-only. */
 export function runSettingsMigrations(raw) {
     const current = raw;
     if (!current.global || typeof current.global !== 'object') {
@@ -190,16 +201,20 @@ function writeSettings(settings) {
     fs.writeFileSync(tmpPath, JSON.stringify(settings, null, 2), 'utf-8');
     fs.renameSync(tmpPath, settingsFilePath);
 }
+/** Read and return the full settings object, creating defaults if missing. */
 export function getSettings() {
     return readSettings();
 }
+/** Return only the global settings section. */
 export function getGlobalSettings() {
     return readSettings().global;
 }
+/** Return project-specific settings, or null if the project is not configured. */
 export function getProjectSettings(projectPath) {
     const settings = readSettings();
     return settings.projects.find((p) => p.path === projectPath) ?? null;
 }
+/** Compute effective settings for a project (project overrides merged with global defaults). */
 export function getEffectiveSettings(projectPath) {
     const settings = readSettings();
     const project = settings.projects.find((p) => p.path === projectPath) ?? null;
@@ -224,14 +239,24 @@ export function getEffectiveSettings(projectPath) {
         setupScript: project.setupScript || '',
     };
 }
+/** Merge partial updates into global settings and persist. */
 export function updateGlobalSettings(data) {
     const settings = readSettings();
-    const allowedGlobalKeys = ['defaultModel', 'dangerouslySkipPermissions', 'prPromptTemplate', 'gitConventions'];
+    const allowedGlobalKeys = [
+        'defaultModel',
+        'dangerouslySkipPermissions',
+        'prPromptTemplate',
+        'gitConventions',
+        'editorCommand',
+        'browserNotifications',
+        'audioNotifications',
+    ];
     const filtered = pickKnownKeys(data, allowedGlobalKeys);
     settings.global = { ...settings.global, ...filtered };
     writeSettings(settings);
     return settings.global;
 }
+/** Create or update project-specific settings. Merges devServer fields on update. */
 export function upsertProject(projectPath, data) {
     const allowedProjectKeys = [
         'displayName',
@@ -276,11 +301,13 @@ export function upsertProject(projectPath, data) {
     writeSettings(settings);
     return settings.projects.find((p) => p.path === projectPath);
 }
+/** Remove a project from the settings file. */
 export function deleteProject(projectPath) {
     const settings = readSettings();
     settings.projects = settings.projects.filter((p) => p.path !== projectPath);
     writeSettings(settings);
 }
+/** List all configured projects. */
 export function listProjects() {
     return readSettings().projects;
 }

package/dist/server/services/setup-script-service.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as wsService from './websocket-service.js';
 const SETUP_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+/** Execute a setup script in a worktree, streaming output via WebSocket. Resolves with the exit code. */
 export function runSetupScript(workspaceId, worktreePath, script, env, timeoutMs = SETUP_TIMEOUT_MS) {
     return new Promise((resolve) => {
         const scriptPath = path.join(worktreePath, '.ai', '.setup-script.tmp');

package/dist/server/services/websocket-service.js

@@ -3,14 +3,16 @@ import { getDb } from '../db/index.js';
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Maps each WS client to the set of workspaceIds they are subscribed to */
 const clients = new Map();
-/** I6: Per-workspace emit counter for periodic cleanup */
+/** Per-workspace emit counter for periodic cleanup. */
 const emitCounters = new Map();
 const EMIT_CLEANUP_THRESHOLD = 2000;
 let messageHandler = null;
+/** Register the handler that processes routed WS messages (e.g. chat:message, workspace:start). */
 export function setMessageHandler(handler) {
     messageHandler = handler;
 }
 // ── Connection handling ────────────────────────────────────────────────────────
+/** Handle a new WebSocket connection: register, dispatch messages, ping keepalive. */
 export function handleConnection(ws) {
     // Register client with empty subscription set
     clients.set(ws, new Set());
@@ -50,7 +52,6 @@ export function handleConnection(ws) {
             case 'sync:request': {
                 const p = payload;
                 const lastEventId = p?.lastEventId ?? '';
-                // I2: Accept optional workspaceIds so the client can sync even before re-subscribing
                 const workspaceIds = p?.workspaceIds;
                 handleSyncRequest(ws, lastEventId, workspaceIds);
                 break;
@@ -97,11 +98,11 @@ export function handleConnection(ws) {
 export function emit(workspaceId, type, payload, sessionId) {
     const id = nanoid();
     const createdAt = new Date().toISOString();
-    // C3: Persist to DB — best-effort only; don't let FK violation (deleted workspace) break the broadcast
+    // Best-effort persist — don't let FK violation (deleted workspace) break the broadcast
     try {
         const db = getDb();
         db.prepare('INSERT INTO ws_events (id, workspace_id, type, payload, session_id, created_at) VALUES (?, ?, ?, ?, ?, ?)').run(id, workspaceId, type, JSON.stringify(payload), sessionId ?? null, createdAt);
-        // I6: Periodic cleanup — increment counter and trigger cleanup when threshold is reached
+        // Periodic cleanup — trigger when emit threshold is reached
         const count = (emitCounters.get(workspaceId) ?? 0) + 1;
         if (count >= EMIT_CLEANUP_THRESHOLD) {
             cleanupOldEvents(workspaceId);
@@ -142,12 +143,10 @@ export function emitEphemeral(workspaceId, type, payload) {
 }
 // ── Sync (replay missed events) ────────────────────────────────────────────────
 /**
- * Sends all events after lastEventId for workspaces the client is subscribed to.
- * I2: If workspaceIds is provided, use those instead of the client's current subscriptions
- * so the client can sync even before re-subscribing (e.g. after a reconnect).
+ * Replay all events after lastEventId for workspaces the client is subscribed to.
+ * If workspaceIds is provided, uses those instead of the client's current subscriptions.
  */
 export function handleSyncRequest(ws, lastEventId, workspaceIds) {
-    // I2: Use provided workspaceIds first, fall back to current subscriptions
     const resolvedIds = workspaceIds && workspaceIds.length > 0
         ? workspaceIds
         : (() => {
@@ -171,7 +170,7 @@ export function handleSyncRequest(ws, lastEventId, workspaceIds) {
                 .all(...resolvedIds, lastRow.rowid);
         }
         else {
-            // I7: lastEventId not found — send events capped to avoid unbounded memory usage
+            // lastEventId not found — send events capped to avoid unbounded memory usage
             rows = db
                 .prepare(`SELECT * FROM ws_events WHERE workspace_id IN (${placeholders}) ORDER BY rowid ASC LIMIT 10000`)
                 .all(...resolvedIds);

package/dist/server/services/workspace-service.js

@@ -1,6 +1,6 @@
 import { nanoid } from 'nanoid';
 import { getDb } from '../db/index.js';
-// Valid status transitions
+/** Allowed status transitions per current status. Enforced by updateWorkspaceStatus. */
 const VALID_TRANSITIONS = {
     created: ['extracting', 'brainstorming', 'idle', 'error'],
     extracting: ['extracting', 'brainstorming', 'idle', 'error'],
@@ -24,6 +24,7 @@ function mapWorkspace(row) {
         model: row.model,
         permissionMode: (row.permission_mode ?? 'auto-accept'),
         devServerStatus: row.dev_server_status,
+        hasUnread: row.has_unread === 1,
         archivedAt: row.archived_at,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
@@ -41,6 +42,7 @@ function mapTask(row) {
         updatedAt: row.updated_at,
     };
 }
+/** Insert a new workspace into the database and return it. */
 export function createWorkspace(data) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -51,11 +53,13 @@ export function createWorkspace(data) {
   `).run(id, data.name, data.projectPath, data.sourceBranch, data.workingBranch, data.notionUrl ?? null, data.notionPageId ?? null, data.model ?? 'claude-opus-4-6', now, now);
     return getWorkspace(id);
 }
+/** Fetch a single workspace by ID, or null if not found. */
 export function getWorkspace(id) {
     const db = getDb();
     const row = db.prepare('SELECT * FROM workspaces WHERE id = ?').get(id);
     return row ? mapWorkspace(row) : null;
 }
+/** List all workspaces, optionally including archived ones. Ordered by most recently updated. */
 export function listWorkspaces(includeArchived = false) {
     const db = getDb();
     const sql = includeArchived
@@ -64,6 +68,7 @@ export function listWorkspaces(includeArchived = false) {
     const rows = db.prepare(sql).all();
     return rows.map(mapWorkspace);
 }
+/** List only archived workspaces, ordered by archive date descending. */
 export function listArchivedWorkspaces() {
     const db = getDb();
     const rows = db
@@ -71,6 +76,7 @@ export function listArchivedWorkspaces() {
         .all();
     return rows.map(mapWorkspace);
 }
+/** Transition a workspace to a new status, validating against VALID_TRANSITIONS. */
 export function updateWorkspaceStatus(id, status) {
     const db = getDb();
     const workspace = getWorkspace(id);
@@ -85,6 +91,7 @@ export function updateWorkspaceStatus(id, status) {
     db.prepare('UPDATE workspaces SET status = ?, updated_at = ? WHERE id = ?').run(status, now, id);
     return getWorkspace(id);
 }
+/** Update a workspace's display name. */
 export function updateWorkspaceName(id, name) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -94,6 +101,7 @@ export function updateWorkspaceName(id, name) {
     }
     return getWorkspace(id);
 }
+/** Update the Claude model used by a workspace's agent. */
 export function updateWorkspaceModel(id, model) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -103,6 +111,7 @@ export function updateWorkspaceModel(id, model) {
     }
     return getWorkspace(id);
 }
+/** Update the agent's permission mode (auto-accept vs plan/read-only). */
 export function updateWorkspacePermissionMode(id, permissionMode) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -114,17 +123,29 @@ export function updateWorkspacePermissionMode(id, permissionMode) {
     }
     return getWorkspace(id);
 }
+/** Update the dev-server status column for a workspace. */
 export function updateDevServerStatus(id, status) {
     const db = getDb();
     db.prepare('UPDATE workspaces SET dev_server_status = ? WHERE id = ?').run(status, id);
 }
+/** Mark a workspace as read (has_unread = 0). */
+export function markWorkspaceRead(id) {
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET has_unread = 0 WHERE id = ?').run(id);
+}
+/** Mark a workspace as unread (has_unread = 1). */
+export function markWorkspaceUnread(id) {
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET has_unread = 1 WHERE id = ?').run(id);
+}
+/** Delete a workspace and cascade-delete its tasks. */
 export function deleteWorkspace(id) {
     const db = getDb();
     db.prepare('DELETE FROM workspaces WHERE id = ?').run(id);
 }
+/** Create a new task under a workspace. Throws if the workspace does not exist. */
 export function createTask(workspaceId, data) {
     const db = getDb();
-    // I2: explicit workspace existence check before INSERT
     const exists = db.prepare('SELECT 1 FROM workspaces WHERE id = ?').get(workspaceId);
     if (!exists) {
         throw new Error(`Workspace not found: '${workspaceId}'`);
@@ -138,11 +159,13 @@ export function createTask(workspaceId, data) {
     const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
     return mapTask(row);
 }
+/** Fetch a single task by ID scoped to a workspace, or null if not found. */
 export function getTask(taskId, workspaceId) {
     const db = getDb();
     const row = db.prepare('SELECT * FROM tasks WHERE id = ? AND workspace_id = ?').get(taskId, workspaceId);
     return row ? mapTask(row) : null;
 }
+/** List all tasks for a workspace, ordered by sort_order ascending. */
 export function listTasks(workspaceId) {
     const db = getDb();
     const rows = db
@@ -150,6 +173,7 @@ export function listTasks(workspaceId) {
         .all(workspaceId);
     return rows.map(mapTask);
 }
+/** Update a task's status (pending, in_progress, done). */
 export function updateTaskStatus(taskId, status) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -160,6 +184,7 @@ export function updateTaskStatus(taskId, status) {
     }
     return mapTask(row);
 }
+/** Update a task's title. Throws if the title is empty or the task does not exist. */
 export function updateTaskTitle(taskId, title) {
     if (!title?.trim()) {
         throw new Error('Task title cannot be empty');
@@ -173,10 +198,12 @@ export function updateTaskTitle(taskId, title) {
     const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(taskId);
     return mapTask(row);
 }
+/** Delete a task by ID. */
 export function deleteTask(taskId) {
     const db = getDb();
     db.prepare('DELETE FROM tasks WHERE id = ?').run(taskId);
 }
+/** Fetch a workspace with all its tasks eagerly loaded. */
 export function getWorkspaceWithTasks(id) {
     const workspace = getWorkspace(id);
     if (!workspace)
@@ -184,6 +211,7 @@ export function getWorkspaceWithTasks(id) {
     const tasks = listTasks(id);
     return { ...workspace, tasks };
 }
+/** Archive a workspace (set archived_at). Throws if already archived. */
 export function archiveWorkspace(id) {
     const db = getDb();
     const workspace = getWorkspace(id);
@@ -197,6 +225,7 @@ export function archiveWorkspace(id) {
     db.prepare('UPDATE workspaces SET archived_at = ?, updated_at = ? WHERE id = ?').run(now, now, id);
     return getWorkspace(id);
 }
+/** Unarchive a workspace (clear archived_at), restoring its previous status. */
 export function unarchiveWorkspace(id) {
     const db = getDb();
     const workspace = getWorkspace(id);
@@ -221,6 +250,7 @@ function mapSession(row) {
         endedAt: row.ended_at,
     };
 }
+/** List all agent sessions for a workspace, most recent first. */
 export function listSessions(workspaceId) {
     const db = getDb();
     const rows = db
@@ -228,6 +258,7 @@ export function listSessions(workspaceId) {
         .all(workspaceId);
     return rows.map(mapSession);
 }
+/** Get the most recent agent session for a workspace, or null if none exist. */
 export function getLatestSession(workspaceId) {
     const db = getDb();
     const row = db

package/dist/server/services/worktree-service.js

@@ -35,10 +35,10 @@ function removeFromExclude(projectPath, worktreePath) {
     const entry = `/${relativePath}`;
     const lines = fs.readFileSync(excludeFile, 'utf-8').split('\n');
     const filtered = lines.filter((line) => line !== entry);
-    // I3: ensure the file ends with exactly one newline and has no trailing empty lines
     const trimmed = filtered.join('\n').replace(/\n+$/, '');
     fs.writeFileSync(excludeFile, trimmed ? `${trimmed}\n` : '', 'utf-8');
 }
+/** Create a git worktree under `.worktrees/` for the given branch. Returns the worktree path. */
 export function createWorktree(projectPath, branchName, sourceBranch) {
     const worktreesDir = path.join(projectPath, '.worktrees');
     if (!fs.existsSync(worktreesDir)) {
@@ -51,7 +51,6 @@ export function createWorktree(projectPath, branchName, sourceBranch) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        // M3: use shared utility for branch-exists detection
         // If branch already exists, add worktree without creating the branch
         if (isGitBranchExistsError(message)) {
             git(projectPath, ['worktree', 'add', worktreePath, branchName]);
@@ -63,6 +62,7 @@ export function createWorktree(projectPath, branchName, sourceBranch) {
     addToExclude(projectPath, worktreePath);
     return worktreePath;
 }
+/** Remove a git worktree and clean up the .git/info/exclude entry. */
 export function removeWorktree(projectPath, worktreePath) {
     try {
         git(projectPath, ['worktree', 'remove', worktreePath, '--force']);
@@ -73,6 +73,7 @@ export function removeWorktree(projectPath, worktreePath) {
     }
     removeFromExclude(projectPath, worktreePath);
 }
+/** List all git worktrees for a repository by parsing `git worktree list --porcelain`. */
 export function listWorktrees(projectPath) {
     const output = git(projectPath, ['worktree', 'list', '--porcelain']);
     const worktrees = [];
@@ -106,6 +107,7 @@ export function listWorktrees(projectPath) {
     }
     return worktrees;
 }
+/** Check whether a worktree for the given branch already exists. */
 export function worktreeExists(projectPath, branchName) {
     try {
         const worktrees = listWorktrees(projectPath);

package/dist/server/utils/git-ops.js

@@ -6,9 +6,11 @@ const execFileAsync = promisify(execFileCb);
 function git(repoPath, args) {
     return execFileSync('git', args, { cwd: repoPath, encoding: 'utf-8' }).trim();
 }
+/** Return the name of the currently checked-out branch. */
 export function getCurrentBranch(repoPath) {
     return git(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
 }
+/** List all local branch names in the repository. */
 export function listBranches(repoPath) {
     const output = git(repoPath, ['branch', '--format=%(refname:short)']);
     return output
@@ -16,20 +18,19 @@ export function listBranches(repoPath) {
         .map((b) => b.trim())
         .filter(Boolean);
 }
+/** Thrown when attempting to create a branch that already exists. */
 export class BranchAlreadyExistsError extends Error {
     constructor(branchName) {
         super(`Branch '${branchName}' already exists`);
         this.name = 'BranchAlreadyExistsError';
     }
 }
-/**
- * M3: Shared utility to detect "branch already exists" git error messages
- * across different locales (English, French, Russian).
- */
+/** Detect "branch already exists" git error messages across locales (EN, FR, RU). */
 export function isGitBranchExistsError(message) {
     const lower = message.toLowerCase();
     return lower.includes('already exists') || lower.includes('existe') || lower.includes('существует');
 }
+/** Create a new local branch from the given source branch. */
 export function createBranch(repoPath, branchName, sourceBranch) {
     try {
         git(repoPath, ['branch', branchName, sourceBranch]);
@@ -42,6 +43,7 @@ export function createBranch(repoPath, branchName, sourceBranch) {
         throw new Error(`Failed to create branch '${branchName}' from '${sourceBranch}': ${message}`);
     }
 }
+/** Return shortstat diff stats for staged (cached) changes. */
 export function getDiffStats(repoPath) {
     try {
         const output = git(repoPath, ['diff', '--cached', '--shortstat']);
@@ -64,6 +66,7 @@ function parseDiffShortstat(output) {
         deletions: deleteMatch ? parseInt(deleteMatch[1], 10) : 0,
     };
 }
+/** List remote-tracking branch names. Returns empty array on failure. */
 export function listRemoteBranches(repoPath) {
     try {
         const output = git(repoPath, ['branch', '-r', '--format=%(refname:short)']);
@@ -76,6 +79,7 @@ export function listRemoteBranches(repoPath) {
         return [];
     }
 }
+/** Force-delete a local branch (`git branch -D`). */
 export function deleteLocalBranch(repoPath, branchName) {
     try {
         git(repoPath, ['branch', '-D', branchName]);
@@ -85,6 +89,7 @@ export function deleteLocalBranch(repoPath, branchName) {
         throw new Error(`Failed to delete local branch '${branchName}': ${message}`);
     }
 }
+/** Delete a branch on the remote (`git push --delete`). */
 export function deleteRemoteBranch(repoPath, branchName, remote = 'origin') {
     try {
         git(repoPath, ['push', remote, '--delete', branchName]);
@@ -94,6 +99,7 @@ export function deleteRemoteBranch(repoPath, branchName, remote = 'origin') {
         throw new Error(`Failed to delete remote branch '${remote}/${branchName}': ${message}`);
     }
 }
+/** Push a branch to the remote with upstream tracking (`git push -u`). */
 export function pushBranch(repoPath, branchName, remote = 'origin') {
     try {
         git(repoPath, ['push', '-u', remote, branchName]);
@@ -119,6 +125,7 @@ function resolveBase(repoPath, base) {
         }
     }
 }
+/** Count commits between base and head (`git rev-list --count`). Returns 0 on failure. */
 export function getCommitCount(repoPath, base, head) {
     try {
         const ref = resolveBase(repoPath, base);
@@ -129,6 +136,7 @@ export function getCommitCount(repoPath, base, head) {
         return 0;
     }
 }
+/** Return structured diff shortstat between two refs (three-dot merge base). */
 export function getStructuredDiffStatsBetween(repoPath, base, head) {
     try {
         const ref = resolveBase(repoPath, base);
@@ -139,6 +147,7 @@ export function getStructuredDiffStatsBetween(repoPath, base, head) {
         return { filesChanged: 0, insertions: 0, deletions: 0 };
     }
 }
+/** Return a formatted list of commit subjects between base and head. */
 export function getCommitsBetween(repoPath, base, head) {
     try {
         const ref = resolveBase(repoPath, base);
@@ -148,6 +157,7 @@ export function getCommitsBetween(repoPath, base, head) {
         return '';
     }
 }
+/** Get the GitHub PR URL for a branch using `gh pr view`. Returns null if no PR exists. */
 export function getPrUrl(repoPath, branchName) {
     try {
         return (execFileSync('gh', ['pr', 'view', branchName, '--json', 'url', '--jq', '.url'], {
@@ -159,6 +169,7 @@ export function getPrUrl(repoPath, branchName) {
         return null;
     }
 }
+/** Get the state and URL of the PR for a branch. Returns null if no PR exists. */
 export function getPrStatus(repoPath, branchName) {
     try {
         const raw = execFileSync('gh', ['pr', 'view', branchName, '--json', 'state,url'], {
@@ -248,6 +259,7 @@ export function getFileContent(repoPath, filePath) {
         return null;
     }
 }
+/** Parse `git status --porcelain` into counts of staged, modified, and untracked files. */
 export function getWorkingTreeStatus(repoPath) {
     try {
         const output = git(repoPath, ['status', '--porcelain']);
@@ -288,6 +300,7 @@ export function getUnpushedCount(repoPath) {
         return -1; // no upstream
     }
 }
+/** Return raw `git diff --shortstat` output between two refs (three-dot). */
 export function getDiffStatsBetween(repoPath, base, head) {
     try {
         return git(repoPath, ['diff', '--shortstat', `${base}...${head}`]);
@@ -298,7 +311,7 @@ export function getDiffStatsBetween(repoPath, base, head) {
 }
 // ── Async versions ───────────────────────────────────────────────────────────
 // Non-blocking alternatives for hot paths (pr-watcher, route handlers).
-// The sync versions above are kept for callers that haven't migrated yet.
+/** Async version of getPrUrl. Returns null if no PR exists. */
 export async function getPrUrlAsync(repoPath, branchName) {
     try {
         const { stdout } = await execFileAsync('gh', ['pr', 'view', branchName, '--json', 'url', '--jq', '.url'], {
@@ -311,6 +324,7 @@ export async function getPrUrlAsync(repoPath, branchName) {
         return null;
     }
 }
+/** Async version of getPrStatus. Returns null if no PR exists. */
 export async function getPrStatusAsync(repoPath, branchName) {
     try {
         const { stdout } = await execFileAsync('gh', ['pr', 'view', branchName, '--json', 'state,url'], {