@loicngr/kobo 1.4.4 → 1.4.6

package/dist/server/routes/workspaces.js

@@ -1,4 +1,4 @@
-import { execFile as execFileCb } from 'node:child_process';
+import { execFile as execFileCb, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -15,8 +15,10 @@ import * as wsService from '../services/websocket-service.js';
 import * as workspaceService from '../services/workspace-service.js';
 import * as worktreeService from '../services/worktree-service.js';
 import * as gitOps from '../utils/git-ops.js';
+/** Hono sub-router for workspace CRUD, tasks, agent lifecycle, git operations, and PR creation. */
 const app = new Hono();
-// GET /api/workspaces — list all workspaces
+/** Tracks workspaces currently running a setup script to prevent concurrent executions. */
+const setupScriptRunning = new Set();
 app.get('/', (c) => {
     try {
         const workspaces = workspaceService.listWorkspaces();
@@ -34,7 +36,7 @@ app.post('/', async (c) => {
         if (!body.name || !body.projectPath || !body.sourceBranch || !body.workingBranch) {
             return c.json({ error: 'Missing required fields: name, projectPath, sourceBranch, workingBranch' }, 400);
         }
-        // 1. Create workspace
+        // Create workspace record
         let workspace = workspaceService.createWorkspace({
             name: body.name,
             projectPath: body.projectPath,
@@ -45,7 +47,7 @@ app.post('/', async (c) => {
             model: body.model,
         });
         let notionContent = null;
-        // 2. If notionUrl provided, extract Notion page
+        // Extract Notion page content if a URL was provided
         if (body.notionUrl) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
             try {
@@ -56,7 +58,7 @@ app.post('/', async (c) => {
                 console.error(`[workspaces] Failed to extract Notion page: ${message}`);
             }
         }
-        // 3. Create tasks from extracted data
+        // Create tasks from extracted Notion data
         if (notionContent) {
             let sortOrder = 0;
             for (const todo of notionContent.todos) {
@@ -104,7 +106,7 @@ app.post('/', async (c) => {
                 }
             }
         }
-        // 4. Create worktree
+        // Create git worktree for the working branch
         let worktreePath;
         try {
             worktreePath = worktreeService.createWorktree(body.projectPath, body.workingBranch, body.sourceBranch);
@@ -114,21 +116,23 @@ app.post('/', async (c) => {
             workspaceService.updateWorkspaceStatus(workspace.id, 'error');
             return c.json({ error: `Failed to create worktree: ${message}` }, 500);
         }
-        // 4b. Ensure Kobo-generated files inside .ai/ are gitignored (the .ai/ dir
-        //     itself may contain project files that SHOULD be committed).
+        // Ensure Kobo-generated files inside .ai/ are gitignored (the .ai/ dir
+        // itself may contain project files that SHOULD be committed).
         try {
             const gitignorePath = path.join(worktreePath, '.gitignore');
             const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
             const lines = existing.split('\n').map((l) => l.trim());
             const toAdd = [];
-            if (!lines.includes('.ai/git-conventions.md'))
-                toAdd.push('.ai/git-conventions.md');
+            if (!lines.includes('.ai/.git-conventions.md'))
+                toAdd.push('.ai/.git-conventions.md');
             if (!lines.includes('.ai/thoughts/'))
                 toAdd.push('.ai/thoughts/');
             if (!lines.includes('.ai/images/'))
                 toAdd.push('.ai/images/');
             if (!lines.includes('.ai/.setup-script.tmp'))
                 toAdd.push('.ai/.setup-script.tmp');
+            if (!lines.includes('.mcp.json'))
+                toAdd.push('.mcp.json');
             if (toAdd.length > 0) {
                 const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
                 fs.appendFileSync(gitignorePath, `${separator}${toAdd.join('\n')}\n`, 'utf-8');
@@ -137,20 +141,20 @@ app.post('/', async (c) => {
         catch (err) {
             console.error('[workspaces] Failed to update .gitignore:', err);
         }
-        // 4c. Write git conventions to the worktree if configured
+        // Write git conventions to the worktree if configured
         const effectiveSettings = settingsService.getEffectiveSettings(body.projectPath);
         if (effectiveSettings.gitConventions) {
             try {
                 const aiDir = path.join(worktreePath, '.ai');
                 fs.mkdirSync(aiDir, { recursive: true });
-                const conventionsPath = path.join(aiDir, 'git-conventions.md');
+                const conventionsPath = path.join(aiDir, '.git-conventions.md');
                 fs.writeFileSync(conventionsPath, effectiveSettings.gitConventions, 'utf-8');
             }
             catch (err) {
-                console.error('[workspaces] Failed to write git-conventions.md:', err);
+                console.error('[workspaces] Failed to write .git-conventions.md:', err);
             }
         }
-        // 4d. Run setup script if configured
+        // Run setup script if configured
         let setupScriptFailed = false;
         if (effectiveSettings.setupScript) {
             workspaceService.updateWorkspaceStatus(workspace.id, 'extracting');
@@ -174,7 +178,7 @@ app.post('/', async (c) => {
                 setupScriptFailed = true;
             }
         }
-        // 5. Save Notion content as markdown in worktree
+        // Save Notion content as markdown in worktree
         let notionFilePath = null;
         if (notionContent && body.notionUrl) {
             try {
@@ -215,9 +219,9 @@ app.post('/', async (c) => {
         }
         // Skip agent launch if setup script failed — workspace stays in 'error' status
         if (!setupScriptFailed) {
-            // 6. Update workspace status to 'brainstorming'
+            // Transition to brainstorming and build the initial agent prompt
             workspaceService.updateWorkspaceStatus(workspace.id, 'brainstorming');
-            // 6. Build prompt with tasks and acceptance criteria
+            // Build prompt with tasks and acceptance criteria
             const allTasks = workspaceService.listTasks(workspace.id);
             const todos = allTasks.filter((t) => !t.isAcceptanceCriterion);
             const criteria = allTasks.filter((t) => t.isAcceptanceCriterion);
@@ -243,7 +247,7 @@ app.post('/', async (c) => {
                 brainstormPrompt += `\nAs you implement the work and validate each criterion, call mark_task_done with the corresponding task_id. Call list_tasks first to see the current IDs.\n`;
             }
             if (effectiveSettings.gitConventions) {
-                brainstormPrompt += `\n# Git conventions\nIMPORTANT: Before any git operation (commit, branch, rebase, merge, push), read and apply the conventions defined in \`.ai/git-conventions.md\`. They are project-specific and override any default behavior. Re-read this file if you're unsure or if context was compacted.\n`;
+                brainstormPrompt += `\n# Git conventions\nIMPORTANT: Before any git operation (commit, branch, rebase, merge, push), read and apply the conventions defined in \`.ai/.git-conventions.md\`. They are project-specific and override any default behavior. Re-read this file if you're unsure or if context was compacted.\n`;
             }
             brainstormPrompt += `\nIMPORTANT: Start by reading CLAUDE.md and/or AGENTS.md at the project root if they exist — they contain project conventions and instructions you must follow.`;
             brainstormPrompt += `\n\nThen brainstorm the implementation approach. Explore the codebase to understand the existing structure. Ask clarifying questions if needed. When you're done brainstorming and have a clear plan, create a plan file and proceed with implementation. Once you have completed the brainstorming phase, output [BRAINSTORM_COMPLETE] on its own line.`;
@@ -576,6 +580,82 @@ app.patch('/:id', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
+/** Open the workspace worktree in the user's configured editor. */
+app.post('/:id/open-editor', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        const globalSettings = settingsService.getGlobalSettings();
+        if (!globalSettings.editorCommand) {
+            return c.json({ error: 'No editor command configured' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        if (!fs.existsSync(worktreePath)) {
+            return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
+        }
+        const child = spawn(globalSettings.editorCommand, [worktreePath], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return c.json({ success: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+/** Re-run the project setup script in the workspace worktree. */
+app.post('/:id/run-setup-script', async (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        if (setupScriptRunning.has(id)) {
+            return c.json({ error: 'Setup script is already running for this workspace' }, 409);
+        }
+        // Stop the running agent before re-running the setup script
+        try {
+            if (agentManager.getAgentStatus(id)) {
+                agentManager.stopAgent(id);
+            }
+        }
+        catch {
+            /* best-effort — agent may already be stopped */
+        }
+        const effectiveSettings = settingsService.getEffectiveSettings(workspace.projectPath);
+        if (!effectiveSettings.setupScript) {
+            return c.json({ error: 'No setup script configured' }, 400);
+        }
+        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        if (!fs.existsSync(worktreePath)) {
+            return c.json({ error: `Worktree path does not exist: ${worktreePath}` }, 400);
+        }
+        setupScriptRunning.add(id);
+        try {
+            const result = await runSetupScript(workspace.id, worktreePath, effectiveSettings.setupScript, {
+                workspaceName: workspace.name,
+                branchName: workspace.workingBranch,
+                sourceBranch: workspace.sourceBranch,
+                projectPath: workspace.projectPath,
+            });
+            if (result.exitCode !== 0) {
+                return c.json({ error: `Setup script failed with exit code ${result.exitCode}` }, 500);
+            }
+            return c.json({ success: true });
+        }
+        finally {
+            setupScriptRunning.delete(id);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/archive — mark workspace as archived (soft-delete)
 app.post('/:id/archive', (c) => {
     try {
@@ -641,14 +721,14 @@ app.delete('/:id', async (c) => {
         const body = await c.req
             .json()
             .catch(() => ({}));
-        // 1. Stop agent if running
+        // Stop agent if running (best-effort)
         try {
             agentManager.stopAgent(id);
         }
         catch {
             // Agent may not be running — ignore
         }
-        // 2. Remove worktree
+        // Remove worktree
         const worktreesDir = `${workspace.projectPath}/.worktrees`;
         const worktreePath = `${worktreesDir}/${workspace.workingBranch}`;
         try {
@@ -658,7 +738,7 @@ app.delete('/:id', async (c) => {
             const message = err instanceof Error ? err.message : String(err);
             console.error(`[workspaces] Failed to remove worktree: ${message}`);
         }
-        // 3. Delete local branch if requested
+        // Delete local branch if requested
         if (body.deleteLocalBranch) {
             try {
                 gitOps.deleteLocalBranch(workspace.projectPath, workspace.workingBranch);
@@ -668,7 +748,7 @@ app.delete('/:id', async (c) => {
                 console.error(`[workspaces] Failed to delete local branch: ${message}`);
             }
         }
-        // 4. Delete remote branch if requested
+        // Delete remote branch if requested
         if (body.deleteRemoteBranch) {
             try {
                 gitOps.deleteRemoteBranch(workspace.projectPath, workspace.workingBranch);
@@ -678,7 +758,7 @@ app.delete('/:id', async (c) => {
                 console.error(`[workspaces] Failed to delete remote branch: ${message}`);
             }
         }
-        // 5. Delete workspace from DB
+        // Delete workspace from DB (cascades to tasks, sessions, events)
         workspaceService.deleteWorkspace(id);
         return new Response(null, { status: 204 });
     }
@@ -823,7 +903,7 @@ app.post('/:id/open-pr', async (c) => {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
         const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
-        // 1. Check branch is on remote
+        // Verify branch exists on remote
         let lsRemoteOut = '';
         try {
             const { stdout } = await execFileAsync('git', ['ls-remote', '--heads', 'origin', workspace.workingBranch], {
@@ -837,7 +917,7 @@ app.post('/:id/open-pr', async (c) => {
         if (!lsRemoteOut.trim()) {
             return c.json({ error: 'Branch is not on remote', code: 'branch_not_pushed' }, 409);
         }
-        // 2. Check all local commits are pushed
+        // Ensure all local commits are pushed
         try {
             const { stdout } = await execFileAsync('git', ['rev-list', '@{u}..HEAD', '--count'], { cwd: worktreePath });
             const countStr = stdout.trim();
@@ -855,7 +935,7 @@ app.post('/:id/open-pr', async (c) => {
             }
             return c.json({ error: `Failed to check branch state: ${message}` }, 500);
         }
-        // 3. Create PR via gh
+        // Create PR via GitHub CLI
         let ghOutput;
         try {
             const placeholderBody = 'Automated PR — description will be updated by the agent.';
@@ -878,7 +958,7 @@ app.post('/:id/open-pr', async (c) => {
             const stderr = err.stderr?.toString() ?? '';
             return c.json({ error: `gh pr create failed: ${message} ${stderr}`.trim() }, 500);
         }
-        // 4. Parse PR URL and number
+        // Parse PR URL and number from gh output
         const urlMatch = ghOutput.match(/https:\/\/github\.com\/[^\s]+\/pull\/(\d+)/);
         if (!urlMatch) {
             return c.json({ error: 'Could not parse PR URL from gh output' }, 500);
@@ -886,12 +966,12 @@ app.post('/:id/open-pr', async (c) => {
         const prUrl = urlMatch[0];
         const prNumber = parseInt(urlMatch[1], 10);
         // ── From here on, PR exists. No more 5xx responses. ──
-        // 5. Resolve the template; skip message steps if empty
+        // Resolve the PR prompt template; skip message steps if empty
         const effective = settingsService.getEffectiveSettings(workspace.projectPath);
         if (!effective.prPromptTemplate) {
             return c.json({ ok: true, prNumber, prUrl, messageSent: false });
         }
-        // 6. Build context and render the template
+        // Build context and render the PR prompt template
         const commits = gitOps.getCommitsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const diffStats = gitOps.getDiffStatsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const tasks = workspaceService.listTasks(workspace.id);
@@ -903,11 +983,11 @@ app.post('/:id/open-pr', async (c) => {
             diffStats,
             tasks,
         });
-        // 7. Emit user:message into the chat feed
+        // Emit user:message into the chat feed
         const session = workspaceService.getLatestSession(workspace.id);
         const sessionId = session?.claudeSessionId ?? undefined;
         wsService.emit(workspace.id, 'user:message', { content: rendered, sender: 'user' }, sessionId);
-        // 8. Send to the running agent, or resume the agent with the PR prompt
+        // Send to the running agent, or resume the agent with the PR prompt
         let messageSent = false;
         try {
             agentManager.sendMessage(workspace.id, rendered);
@@ -933,6 +1013,23 @@ app.post('/:id/open-pr', async (c) => {
         return c.json({ error: message }, 500);
     }
 });
+/** POST /api/workspaces/:id/mark-read — mark workspace as read (clear unread indicator). */
+app.post('/:id/mark-read', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        workspaceService.markWorkspaceRead(id);
+        wsService.emitEphemeral(id, 'workspace:unread', { hasUnread: false });
+        return c.json({ success: true });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/stop — stop agent
 app.post('/:id/stop', (c) => {
     try {

package/dist/server/services/agent-manager.js

@@ -7,8 +7,8 @@ import { getDb } from '../db/index.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../utils/paths.js';
 import { registerProcess, unregisterProcess } from '../utils/process-tracker.js';
 import { getEffectiveSettings } from './settings-service.js';
-import { emit } from './websocket-service.js';
-import { getWorkspace as getWs, listTasks, updateWorkspaceStatus } from './workspace-service.js';
+import { emit, emitEphemeral } from './websocket-service.js';
+import { getWorkspace as getWs, listTasks, markWorkspaceUnread, updateWorkspaceStatus } from './workspace-service.js';
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Actual bound port of the running backend — set at startup via setBackendPort() */
 let backendPort = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
@@ -82,6 +82,13 @@ function runWatchdog() {
         catch {
             // Transition may not be valid — ignore
         }
+        try {
+            markWorkspaceUnread(workspaceId);
+            emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+        }
+        catch {
+            // best-effort
+        }
         emit(workspaceId, 'agent:status', { status: 'error', message: 'Agent process died unexpectedly' }, agent.claudeSessionId);
     }
 }
@@ -100,6 +107,7 @@ export function stopWatchdog() {
     }
 }
 // ── Start agent ────────────────────────────────────────────────────────────────
+/** Spawn a Claude Code CLI process for a workspace and wire up stdout/stderr/exit handling. */
 export function startAgent(workspaceId, workingDir, prompt, model, resume = false, permissionMode = 'auto-accept') {
     // Check if agent already running for this workspace
     if (agents.has(workspaceId)) {
@@ -301,7 +309,6 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     });
     // ── stderr — detect quota / rate limit errors ──
     proc.stderr?.on('data', (data) => {
-        // I1: Don't process quota errors if the agent is already stopping or gone
         const currentAgent = agents.get(workspaceId);
         if (!currentAgent || currentAgent.status === 'stopping')
             return;
@@ -322,7 +329,6 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         catch {
             // File may not exist (spawn failed) — ignore
         }
-        // I3: Close readline interface to release the stream reference
         agent.rl.close();
         unregisterProcess(workspaceId);
         // Only remove from the map if this exact agent instance is still current.
@@ -334,7 +340,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         }
         // Clean up retry state and inactivity timer
         retryCounts.delete(workspaceId);
-        // C2: Clear the kill timer if it's still pending (process exited naturally before SIGKILL)
+        // Clear the kill timer if it's still pending (process exited naturally before SIGKILL)
         const pendingKillTimer = killTimers.get(workspaceId);
         if (pendingKillTimer) {
             clearTimeout(pendingKillTimer);
@@ -350,7 +356,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             emit(workspaceId, 'agent:status', { status: 'stopped' }, agent.claudeSessionId);
             return;
         }
-        // C1: Also clear backoff timers on non-stopping exit
+        // Also clear backoff timers on non-stopping exit
         const pendingBackoff = backoffTimers.get(workspaceId);
         if (pendingBackoff) {
             clearTimeout(pendingBackoff);
@@ -363,6 +369,13 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             catch (err) {
                 console.error('[agent] Failed to update workspace status on exit:', err);
             }
+            try {
+                markWorkspaceUnread(workspaceId);
+                emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+            }
+            catch {
+                // best-effort
+            }
             emit(workspaceId, 'agent:status', { status: 'error', exitCode: code }, agent.claudeSessionId);
         }
         else {
@@ -372,6 +385,13 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             catch (err) {
                 console.error('[agent] Failed to update workspace status on exit:', err);
             }
+            try {
+                markWorkspaceUnread(workspaceId);
+                emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+            }
+            catch {
+                // best-effort
+            }
             emit(workspaceId, 'agent:status', { status: 'completed' }, agent.claudeSessionId);
         }
     });
@@ -382,6 +402,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     return agent;
 }
 // ── Stop agent ─────────────────────────────────────────────────────────────────
+/** Gracefully stop an agent (SIGTERM, then SIGKILL after 5s). */
 export function stopAgent(workspaceId) {
     const agent = agents.get(workspaceId);
     if (!agent) {
@@ -398,7 +419,6 @@ export function stopAgent(workspaceId) {
         clearTimeout(timer);
         backoffTimers.delete(workspaceId);
     }
-    // I3: Close readline interface now that we're stopping
     try {
         agent.rl.close();
     }
@@ -414,7 +434,7 @@ export function stopAgent(workspaceId) {
     }
     // After 5s timeout, send SIGKILL if still running
     const killTimer = setTimeout(() => {
-        // C2: If a new agent has been started for this workspace in the meantime,
+        // If a new agent has been started for this workspace in the meantime,
         // don't kill the old process — it's handled by the new lifecycle.
         const currentAgent = agents.get(workspaceId);
         if (currentAgent && currentAgent !== agent) {
@@ -436,6 +456,7 @@ export function stopAgent(workspaceId) {
     killTimers.set(workspaceId, killTimer);
 }
 // ── Send message to agent stdin ────────────────────────────────────────────────
+/** Write a user message to the running agent's stdin. */
 export function sendMessage(workspaceId, content) {
     const agent = agents.get(workspaceId);
     if (!agent) {
@@ -447,13 +468,16 @@ export function sendMessage(workspaceId, content) {
     agent.process.stdin.write(`${content}\n`);
 }
 // ── Status queries ─────────────────────────────────────────────────────────────
+/** Get the in-memory status of the agent for a workspace, or null if not running. */
 export function getAgentStatus(workspaceId) {
     const agent = agents.get(workspaceId);
     return agent?.status ?? null;
 }
+/** Return the number of currently running agents. */
 export function getRunningCount() {
     return agents.size;
 }
+/** Return the cached list of slash commands discovered from the last agent init. */
 export function getAvailableSkills() {
     return availableSkills;
 }

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

@@ -8,6 +8,11 @@ import { getWorkspace, updateDevServerStatus } from './workspace-service.js';
 function getWorktreePath(projectPath, workingBranch) {
     return path.join(projectPath, '.worktrees', workingBranch);
 }
+/** Build a clean env for child processes, stripping Kobo-specific variables. */
+function cleanEnv() {
+    const { PORT, SERVER_PORT, ...rest } = process.env;
+    return rest;
+}
 // ── State ──────────────────────────────────────────────────────────────────────
 /** workspaceId -> spawned dev-server process */
 const trackedProcesses = new Map();
@@ -143,7 +148,7 @@ export function startDevServer(workspaceId) {
     const proc = spawn('bash', ['-c', settings.devServer.startCommand], {
         cwd,
         env: {
-            ...process.env,
+            ...cleanEnv(),
             INSTANCE: instanceName,
             DEV_DOCKER_NO_FOLLOW: '1',
         },
@@ -229,7 +234,7 @@ export function stopDevServer(workspaceId) {
             execSync(settings.devServer.stopCommand, {
                 cwd,
                 env: {
-                    ...process.env,
+                    ...cleanEnv(),
                     INSTANCE: instanceName,
                     PROJECT_NAME: config?.projectName ?? '',
                 },

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

@@ -1,4 +1,3 @@
-// src/server/services/image-service.ts
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
@@ -30,6 +29,7 @@ function readIndex(imagesDir) {
 function writeIndex(imagesDir, entries) {
     fs.writeFileSync(path.join(imagesDir, INDEX_FILE), JSON.stringify(entries, null, 2));
 }
+/** Save an image buffer to `.ai/images/` and update the index. Returns the UID and relative path. */
 export async function saveImage(worktreePath, fileBuffer, originalName) {
     const ext = path.extname(originalName).toLowerCase().replace('.', '');
     if (!ext) {
@@ -53,6 +53,7 @@ export async function saveImage(worktreePath, fileBuffer, originalName) {
     });
     return { uid, relativePath: `${IMAGES_DIR}/${filename}` };
 }
+/** Delete an image by UID from disk and the index. */
 export async function deleteImage(worktreePath, uid) {
     const imagesDir = path.join(worktreePath, IMAGES_DIR);
     await withLock(worktreePath, () => {

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 = [];

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);