@loicngr/kobo 1.4.5 → 1.4.7

package/AGENTS.md

@@ -200,7 +200,7 @@ The frontend uses `vue-i18n` v10 with 5 supported locales: English (`en`), Frenc
 
 ### Commit rules (mirrors `DEFAULT_GIT_CONVENTIONS` in `src/server/services/settings-service.ts`)
 
-These rules are the source of truth and are also written to `.ai/git-conventions.md` inside every workspace that the agent creates. Follow them when committing on this repository too.
+These rules are the source of truth and are also written to `.ai/.git-conventions.md` inside every workspace that the agent creates. Follow them when committing on this repository too.
 
 **Commits**
 - Use Conventional Commits: `type(scope): subject`

package/README.md

@@ -16,7 +16,7 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
 - **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
-- **Conventional-commit enforcement** — project-level git conventions are written to `.ai/git-conventions.md` inside every workspace so Claude follows them during commits
+- **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
 - **Pull request automation** — one-click `push` and `open-pr` endpoints integrate with the GitHub CLI, using a configurable prompt template
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
 
@@ -181,7 +181,7 @@ Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defa
 
 - `defaultModel` — Claude model to use (e.g. `claude-opus-4-6`)
 - `prPromptTemplate` — template rendered when opening a PR via the `/open-pr` endpoint; supports `{{pr_number}}`, `{{pr_url}}`, `{{branch_name}}`, `{{diff_stats}}`, `{{commits}}`, etc.
-- `gitConventions` — markdown-formatted git conventions written to `.ai/git-conventions.md` in every workspace so the agent follows them when committing
+- `gitConventions` — markdown-formatted git conventions written to `.ai/.git-conventions.md` in every workspace so the agent follows them when committing
 - `devServer` — per-project `startCommand` / `stopCommand` for launching workspace-scoped dev servers
 
 ## Contributing

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
+/** Allowed task status values. */
 export const VALID_TASK_STATUSES = ['pending', 'in_progress', 'done'];
 function rowToDto(row) {
     return {
@@ -10,12 +11,14 @@ function rowToDto(row) {
         is_acceptance_criterion: row.is_acceptance_criterion === 1,
     };
 }
+/** Return all tasks for a workspace, ordered by sort_order. */
 export function listTasksHandler(db, workspaceId) {
     const rows = db
         .prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE workspace_id = ? ORDER BY sort_order ASC')
         .all(workspaceId);
     return rows.map(rowToDto);
 }
+/** Set a task's status to "done" and return the updated task. */
 export function markTaskDoneHandler(db, workspaceId, taskId) {
     const now = new Date().toISOString();
     const result = db
@@ -29,6 +32,7 @@ export function markTaskDoneHandler(db, workspaceId, taskId) {
         .get(taskId);
     return { success: true, task: rowToDto(row) };
 }
+/** Create a new task appended at the end of the workspace's task list. */
 export function createTaskHandler(db, workspaceId, data) {
     if (!data.title?.trim()) {
         throw new Error('title is required');
@@ -50,6 +54,7 @@ export function createTaskHandler(db, workspaceId, data) {
     const row = db.prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE id = ?').get(id);
     return rowToDto(row);
 }
+/** Update one or more fields of an existing task (title, status, or acceptance criterion flag). */
 export function updateTaskHandler(db, workspaceId, taskId, data) {
     // Verify task belongs to workspace
     const existing = db.prepare('SELECT id FROM tasks WHERE id = ? AND workspace_id = ?').get(taskId, workspaceId);
@@ -87,6 +92,7 @@ export function updateTaskHandler(db, workspaceId, taskId, data) {
         .get(taskId);
     return rowToDto(row);
 }
+/** Permanently delete a task from a workspace. */
 export function deleteTaskHandler(db, workspaceId, taskId) {
     const result = db.prepare('DELETE FROM tasks WHERE id = ? AND workspace_id = ?').run(taskId, workspaceId);
     if (result.changes === 0) {
@@ -94,6 +100,7 @@ export function deleteTaskHandler(db, workspaceId, taskId) {
     }
     return { success: true, task_id: taskId };
 }
+/** Read the dev-server status for a workspace directly from the database. */
 export function getDevServerStatusHandler(db, workspaceId) {
     const row = db.prepare('SELECT dev_server_status FROM workspaces WHERE id = ?').get(workspaceId);
     if (!row) {
@@ -101,6 +108,7 @@ export function getDevServerStatusHandler(db, workspaceId) {
     }
     return { workspaceId, status: row.dev_server_status };
 }
+/** Read global and per-project settings from the JSON file on disk. */
 export function getSettingsHandler(settingsPath, projectPath) {
     // Shape is determined solely by whether projectPath was provided:
     //  - with projectPath → { global, project }
@@ -125,9 +133,10 @@ export function getSettingsHandler(settingsPath, projectPath) {
     }
     return { global, projects };
 }
+/** Fetch workspace metadata from the database, computing the worktree path from project_path and working_branch. */
 export function getWorkspaceInfoHandler(db, workspaceId) {
     const row = db
-        .prepare('SELECT id, name, project_path, source_branch, working_branch, status, notion_url, notion_page_id, model, dev_server_status, created_at, updated_at FROM workspaces WHERE id = ?')
+        .prepare('SELECT id, name, project_path, source_branch, working_branch, status, notion_url, notion_page_id, model, dev_server_status, has_unread, created_at, updated_at FROM workspaces WHERE id = ?')
         .get(workspaceId);
     if (!row) {
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -144,10 +153,12 @@ export function getWorkspaceInfoHandler(db, workspaceId) {
         notionUrl: row.notion_url,
         notionPageId: row.notion_page_id,
         devServerStatus: row.dev_server_status,
+        hasUnread: row.has_unread === 1,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
     };
 }
+/** List images registered in the worktree's `.ai/images/index.json`, resolving each entry to its file path. */
 export function listWorkspaceImagesHandler(worktreePath) {
     const imagesDir = path.join(worktreePath, '.ai', 'images');
     const indexPath = path.join(imagesDir, 'index.json');

package/dist/mcp-server/kobo-tasks-server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -27,6 +29,7 @@ catch (err) {
     console.error('[kobo-tasks-server] Failed to open database:', err);
     process.exit(1);
 }
+/** Fire-and-forget POST to the backend so the UI reflects a task marked as done. */
 async function notifyBackend(taskId) {
     try {
         const url = `${backendUrl}/api/workspaces/${workspaceId}/tasks/${taskId}/notify-done`;
@@ -39,6 +42,7 @@ async function notifyBackend(taskId) {
         console.error('[kobo-tasks-server] notify-done failed:', err);
     }
 }
+/** Fire-and-forget POST to the backend so the UI refreshes the task list after a mutation. */
 async function notifyTasksUpdated() {
     try {
         const url = `${backendUrl}/api/workspaces/${workspaceId}/tasks/notify-updated`;
@@ -48,6 +52,7 @@ async function notifyTasksUpdated() {
         console.error('[kobo-tasks-server] notify-updated failed:', err);
     }
 }
+/** Generic HTTP request to the Kobo backend, returning parsed JSON or null. */
 async function backendRequest(method, pathname, body) {
     const url = `${backendUrl}${pathname}`;
     const init = { method };
@@ -152,7 +157,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'get_dev_server_status',
-            description: 'Check whether the dev server is running for the current workspace.',
+            description: 'Get the live dev server status for the current workspace. Returns status (running/stopped/starting/error/unknown), URL, HTTP port, instance name, project name, and running container names.',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -213,11 +218,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['status'],
             },
         },
+        {
+            name: 'get_notion_ticket',
+            description: 'Get the Notion ticket info for the current workspace. Returns the Notion URL and the extracted ticket content (from .ai/thoughts/) if available.',
+            inputSchema: { type: 'object', properties: {}, required: [] },
+        },
     ],
 }));
+/** Wrap a successful result as an MCP tool response with JSON text content. */
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
+/** Wrap an error message as an MCP tool error response. */
 function fail(message) {
     return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
 }
@@ -271,7 +283,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return ok(getSettingsHandler(settingsPath, a.project_path));
         }
         if (name === 'get_dev_server_status') {
-            return ok(getDevServerStatusHandler(db, workspaceId));
+            try {
+                const result = await backendRequest('GET', `/api/dev-server/${workspaceId}/status`);
+                return ok(result);
+            }
+            catch {
+                // Fallback to DB if the backend HTTP API is unreachable
+                return ok(getDevServerStatusHandler(db, workspaceId));
+            }
         }
         if (name === 'get_workspace_info') {
             return ok(getWorkspaceInfoHandler(db, workspaceId));
@@ -293,6 +312,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const info = getWorkspaceInfoHandler(db, workspaceId);
             return ok(listWorkspaceImagesHandler(info.worktreePath));
         }
+        if (name === 'get_notion_ticket') {
+            const info = getWorkspaceInfoHandler(db, workspaceId);
+            const thoughtsDir = path.join(info.worktreePath, '.ai', 'thoughts');
+            let ticketContent = '';
+            if (fs.existsSync(thoughtsDir)) {
+                const files = fs.readdirSync(thoughtsDir).filter((f) => f.endsWith('.md'));
+                for (const file of files) {
+                    ticketContent += fs.readFileSync(path.join(thoughtsDir, file), 'utf-8') + '\n';
+                }
+            }
+            return ok({
+                notionUrl: info.notionUrl,
+                notionPageId: info.notionPageId,
+                ticketContent: ticketContent.trim() || null,
+            });
+        }
         if (name === 'get_git_info') {
             const result = await backendRequest('GET', `/api/workspaces/${workspaceId}/git-stats`);
             return ok(result);

package/dist/server/db/index.js

@@ -1,6 +1,10 @@
 import Database from 'better-sqlite3';
 import { ensureKoboHome, getDbPath } from '../utils/paths.js';
 let instance = null;
+/**
+ * Return the singleton SQLite database connection, creating it on first call.
+ * Configures WAL mode, busy timeout, and foreign keys.
+ */
 export function getDb(dbPath) {
     if (instance)
         return instance;
@@ -15,6 +19,7 @@ export function getDb(dbPath) {
     instance.pragma('foreign_keys=ON');
     return instance;
 }
+/** Close the singleton database connection and release resources. */
 export function closeDb() {
     if (instance) {
         instance.close();

package/dist/server/db/migrations.js

@@ -1,4 +1,5 @@
 import { initSchema } from './schema.js';
+/** Ordered registry of all schema migrations. Append new entries at the end. */
 export const migrations = [
     {
         version: 2,
@@ -18,9 +19,17 @@ export const migrations = [
       `);
         },
     },
+    {
+        version: 4,
+        name: 'add-has-unread',
+        migrate: (db) => {
+            db.prepare('ALTER TABLE workspaces ADD COLUMN has_unread INTEGER NOT NULL DEFAULT 0').run();
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;
+/** Apply all pending migrations sequentially, or bootstrap a fresh database via initSchema. */
 export function runMigrations(db) {
     // Create the history table (replaces the old single-row schema_version table).
     db.exec(`

package/dist/server/db/schema.js

@@ -1,3 +1,4 @@
+/** Create all tables and indexes for a fresh install. Not used for upgrades -- see migrations.ts. */
 export function initSchema(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS workspaces (
@@ -12,6 +13,7 @@ export function initSchema(db) {
       model TEXT NOT NULL DEFAULT 'claude-opus-4-6',
       permission_mode TEXT NOT NULL DEFAULT 'auto-accept',
       dev_server_status TEXT NOT NULL DEFAULT 'stopped',
+      has_unread INTEGER NOT NULL DEFAULT 0,
       archived_at TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL

package/dist/server/index.js

@@ -20,9 +20,8 @@ import { emit, handleConnection, setMessageHandler } from './services/websocket-
 import { getLatestSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
 import { getClientSpaPath, getKoboHome, getPackageVersion } from './utils/paths.js';
 import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/process-tracker.js';
-// 0. Runtime prerequisite check — warn if claude CLI is missing. Don't block
-// startup: the user may still want to configure settings or browse workspaces
-// before installing Claude Code.
+// Runtime prerequisite check — warn if the claude CLI is missing. Don't block
+// startup: the user may still want to configure settings or browse workspaces.
 {
     const check = spawnSync('claude', ['--version'], { stdio: 'ignore' });
     if (check.error && check.error.code === 'ENOENT') {
@@ -30,18 +29,18 @@ import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/
     }
 }
 console.log(`[kobo] Kōbō home: ${getKoboHome()}`);
-// 1. Initialize DB + run migrations
+// Initialize DB + run migrations
 const db = getDb();
 runMigrations(db);
-// 2. Initialize process cleanup, agent watchdog, and PR watcher
+// Initialize process cleanup, agent watchdog, and PR watcher
 initProcessCleanup();
 startWatchdog();
 startPrWatcher();
-// 3. Create Hono app
+// Create Hono app
 const app = new Hono();
 // Health check (root / is handled by the SPA catch-all below)
 app.get('/api/health', (c) => c.json({ status: 'ok', version: getPackageVersion() }));
-// 4. Mount route sub-routers
+// Mount route sub-routers
 app.route('/api/workspaces', workspacesRouter);
 app.route('/api/workspaces', imagesRouter);
 app.route('/api/notion', notionRouter);
@@ -51,7 +50,7 @@ app.route('/api/dev-server', devServerRouter);
 // Skills endpoint
 app.get('/api/skills', (c) => c.json(getAvailableSkills()));
 const PORT = parseInt(process.env.SERVER_PORT || process.env.PORT || '3000', 10);
-// 9. Serve static files from the built SPA if present (production mode).
+// Serve static files from the built SPA if present (production mode).
 // The path is resolved relative to the package install directory, so this
 // works both in dev (tsx running from src/) and when installed via npm / npx
 // (node running from dist/).
@@ -91,7 +90,7 @@ if (clientDistPath) {
         });
     });
 }
-// 5. Create HTTP server via @hono/node-server
+// Create HTTP server via @hono/node-server
 const server = serve({
     fetch: app.fetch,
     port: PORT,
@@ -99,13 +98,13 @@ const server = serve({
     setBackendPort(info.port);
     console.log(`Server running at http://localhost:${info.port}`);
 });
-// 6. Create WebSocketServer attached to the HTTP server
+// Create WebSocketServer attached to the HTTP server
 const wss = new WebSocketServer({ noServer: true });
-// 7. Wire WebSocket connections to websocket-service.handleConnection()
+// Wire WebSocket connections to websocket-service.handleConnection()
 wss.on('connection', (ws) => {
     handleConnection(ws);
 });
-// 8. Wire websocket-service message handler to agent-manager
+// Wire websocket-service message handler to agent-manager
 setMessageHandler((type, payload) => {
     const p = payload;
     if (type === 'chat:message' && p?.workspaceId && p?.content) {
@@ -182,21 +181,21 @@ server.on('upgrade', (request, socket, head) => {
         socket.destroy();
     }
 });
-// 9. Graceful shutdown handler
+// Graceful shutdown handler
 let isShuttingDown = false;
 function gracefulShutdown(signal) {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
     console.log(`\n[kobo] Received ${signal}, shutting down gracefully…`);
-    // 1. Stop accepting new connections
+    // Stop accepting new connections
     wss.close(() => {
         console.log('[kobo] WebSocket server closed');
     });
     server.close(() => {
         console.log('[kobo] HTTP server closed');
     });
-    // 2. Stop background services
+    // Stop background services
     try {
         stopWatchdog();
     }
@@ -209,7 +208,7 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
-    // 3. Kill all tracked child processes (agents, dev servers)
+    // Kill all tracked child processes (agents, dev servers)
     try {
         killAllTrackedProcesses();
         console.log('[kobo] Tracked processes killed');
@@ -217,7 +216,7 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
-    // 4. Close database
+    // Close database
     try {
         closeDb();
         console.log('[kobo] Database closed');
@@ -225,7 +224,7 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
-    // 4. Give a short grace period for in-flight requests, then exit
+    // Give a short grace period for in-flight requests, then exit
     setTimeout(() => {
         console.log('[kobo] Shutdown complete');
         process.exit(0);

package/dist/server/routes/dev-server.js

@@ -1,6 +1,7 @@
 import { Hono } from 'hono';
 import { getDevServerLogs, getStatus, startDevServer, stopDevServer } from '../services/dev-server-service.js';
 import { getWorkspace } from '../services/workspace-service.js';
+/** Hono sub-router for per-workspace dev server lifecycle (start, stop, status, logs). */
 const app = new Hono();
 // GET /api/dev-server/:workspaceId/status
 app.get('/:workspaceId/status', (c) => {

package/dist/server/routes/git.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { listBranches, listRemoteBranches } from '../utils/git-ops.js';
+/** Hono sub-router for git-related endpoints (branch listing). */
 const app = new Hono();
 // GET /api/git/branches?path=<repoPath> — list branches for a repo
 app.get('/branches', (c) => {

package/dist/server/routes/images.js

@@ -1,8 +1,11 @@
 import { Hono } from 'hono';
 import * as imageService from '../services/image-service.js';
 import * as workspaceService from '../services/workspace-service.js';
+/** Maximum allowed upload size for a single image (10 MB). */
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10 MB
+/** MIME types accepted for image uploads. */
 const ALLOWED_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+/** Hono sub-router for workspace image upload and deletion. */
 const app = new Hono();
 // POST /:id/images — upload an image
 app.post('/:id/images', async (c) => {

package/dist/server/routes/notion.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { extractNotionPage } from '../services/notion-service.js';
+/** Hono sub-router for Notion page extraction. */
 const app = new Hono();
 // POST /api/notion/extract — extract a Notion page
 app.post('/extract', async (c) => {

package/dist/server/routes/settings.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import * as settingsService from '../services/settings-service.js';
+/** Hono sub-router for global and per-project settings CRUD. */
 const app = new Hono();
 // GET /api/settings — return full settings
 app.get('/', (c) => {