@loicngr/kobo 0.1.1

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

@@ -0,0 +1,117 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGitBranchExistsError } from '../utils/git-ops.js';
+function git(repoPath, args) {
+    return execFileSync('git', args, { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+}
+function getExcludeFilePath(projectPath) {
+    return path.join(projectPath, '.git', 'info', 'exclude');
+}
+function addToExclude(projectPath, worktreePath) {
+    const excludeFile = getExcludeFilePath(projectPath);
+    // Ensure the .git/info directory exists
+    const infoDir = path.dirname(excludeFile);
+    if (!fs.existsSync(infoDir)) {
+        fs.mkdirSync(infoDir, { recursive: true });
+    }
+    // Make the path relative to projectPath for cleaner exclude entries
+    const relativePath = path.relative(projectPath, worktreePath);
+    const entry = `/${relativePath}`;
+    let current = '';
+    if (fs.existsSync(excludeFile)) {
+        current = fs.readFileSync(excludeFile, 'utf-8');
+    }
+    if (!current.split('\n').includes(entry)) {
+        const newContent = current.endsWith('\n') || current === '' ? `${current}${entry}\n` : `${current}\n${entry}\n`;
+        fs.writeFileSync(excludeFile, newContent, 'utf-8');
+    }
+}
+function removeFromExclude(projectPath, worktreePath) {
+    const excludeFile = getExcludeFilePath(projectPath);
+    if (!fs.existsSync(excludeFile))
+        return;
+    const relativePath = path.relative(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');
+}
+export function createWorktree(projectPath, branchName, sourceBranch) {
+    const worktreesDir = path.join(projectPath, '.worktrees');
+    if (!fs.existsSync(worktreesDir)) {
+        fs.mkdirSync(worktreesDir, { recursive: true });
+    }
+    const worktreePath = path.join(worktreesDir, branchName);
+    try {
+        // Try creating a new branch + worktree
+        git(projectPath, ['worktree', 'add', '-b', branchName, worktreePath, 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]);
+        }
+        else {
+            throw new Error(`Failed to create worktree for branch '${branchName}': ${message}`);
+        }
+    }
+    addToExclude(projectPath, worktreePath);
+    return worktreePath;
+}
+export function removeWorktree(projectPath, worktreePath) {
+    try {
+        git(projectPath, ['worktree', 'remove', worktreePath, '--force']);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to remove worktree '${worktreePath}': ${message}`);
+    }
+    removeFromExclude(projectPath, worktreePath);
+}
+export function listWorktrees(projectPath) {
+    const output = git(projectPath, ['worktree', 'list', '--porcelain']);
+    const worktrees = [];
+    const blocks = output.split('\n\n').filter(Boolean);
+    for (const block of blocks) {
+        const lines = block.split('\n');
+        const worktree = {};
+        for (const line of lines) {
+            if (line.startsWith('worktree ')) {
+                worktree.path = line.slice('worktree '.length).trim();
+            }
+            else if (line.startsWith('HEAD ')) {
+                worktree.head = line.slice('HEAD '.length).trim();
+            }
+            else if (line.startsWith('branch ')) {
+                // branch refs/heads/<name>
+                const ref = line.slice('branch '.length).trim();
+                worktree.branch = ref.replace(/^refs\/heads\//, '');
+            }
+            else if (line === 'detached') {
+                worktree.branch = '(detached HEAD)';
+            }
+        }
+        if (worktree.path) {
+            worktrees.push({
+                path: worktree.path,
+                branch: worktree.branch ?? '',
+                head: worktree.head ?? '',
+            });
+        }
+    }
+    return worktrees;
+}
+export function worktreeExists(projectPath, branchName) {
+    try {
+        const worktrees = listWorktrees(projectPath);
+        return worktrees.some((wt) => wt.branch === branchName);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,117 @@
+import { execFileSync } from 'node:child_process';
+function git(repoPath, args) {
+    return execFileSync('git', args, { cwd: repoPath, encoding: 'utf-8' }).trim();
+}
+export function getCurrentBranch(repoPath) {
+    return git(repoPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+export function listBranches(repoPath) {
+    const output = git(repoPath, ['branch', '--format=%(refname:short)']);
+    return output
+        .split('\n')
+        .map((b) => b.trim())
+        .filter(Boolean);
+}
+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).
+ */
+export function isGitBranchExistsError(message) {
+    const lower = message.toLowerCase();
+    return lower.includes('already exists') || lower.includes('existe') || lower.includes('существует');
+}
+export function createBranch(repoPath, branchName, sourceBranch) {
+    try {
+        git(repoPath, ['branch', branchName, sourceBranch]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isGitBranchExistsError(message)) {
+            throw new BranchAlreadyExistsError(branchName);
+        }
+        throw new Error(`Failed to create branch '${branchName}' from '${sourceBranch}': ${message}`);
+    }
+}
+export function getDiffStats(repoPath) {
+    try {
+        const output = git(repoPath, ['diff', '--cached', '--shortstat']);
+        return parseDiffShortstat(output);
+    }
+    catch {
+        return { filesChanged: 0, insertions: 0, deletions: 0 };
+    }
+}
+function parseDiffShortstat(output) {
+    if (!output.trim()) {
+        return { filesChanged: 0, insertions: 0, deletions: 0 };
+    }
+    const filesMatch = output.match(/(\d+) file/);
+    const insertMatch = output.match(/(\d+) insertion/);
+    const deleteMatch = output.match(/(\d+) deletion/);
+    return {
+        filesChanged: filesMatch ? parseInt(filesMatch[1], 10) : 0,
+        insertions: insertMatch ? parseInt(insertMatch[1], 10) : 0,
+        deletions: deleteMatch ? parseInt(deleteMatch[1], 10) : 0,
+    };
+}
+export function listRemoteBranches(repoPath) {
+    try {
+        const output = git(repoPath, ['branch', '-r', '--format=%(refname:short)']);
+        return output
+            .split('\n')
+            .map((b) => b.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function deleteLocalBranch(repoPath, branchName) {
+    try {
+        git(repoPath, ['branch', '-D', branchName]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to delete local branch '${branchName}': ${message}`);
+    }
+}
+export function deleteRemoteBranch(repoPath, branchName, remote = 'origin') {
+    try {
+        git(repoPath, ['push', remote, '--delete', branchName]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to delete remote branch '${remote}/${branchName}': ${message}`);
+    }
+}
+export function pushBranch(repoPath, branchName, remote = 'origin') {
+    try {
+        git(repoPath, ['push', '-u', remote, branchName]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to push branch '${branchName}' to '${remote}': ${message}`);
+    }
+}
+export function getCommitsBetween(repoPath, base, head) {
+    try {
+        return git(repoPath, ['log', `${base}..${head}`, '--pretty=format:- %s (%h)', '--no-merges']);
+    }
+    catch {
+        return '';
+    }
+}
+export function getDiffStatsBetween(repoPath, base, head) {
+    try {
+        return git(repoPath, ['diff', '--shortstat', `${base}...${head}`]);
+    }
+    catch {
+        return '';
+    }
+}

package/dist/server/utils/paths.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Package root resolved from this file's location via pure path arithmetic
+// (no filesystem calls, so this stays robust when tests mock `node:fs`).
+// This file lives at `<root>/src/server/utils/paths.ts` in dev (tsx) and at
+// `<root>/dist/server/utils/paths.js` in production (node) — both are exactly
+// three directories deep from the package root.
+//
+// Do NOT move this file without updating the parent count. A unit test in
+// src/__tests__/paths.test.ts verifies the result points at a directory that
+// contains package.json.
+const selfDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(selfDir, '..', '..', '..');
+/**
+ * Resolves a path inside the Kōbō package (e.g. compiled MCP server, built SPA).
+ * Never use this for user data — those go through getKoboHome() / getDataDir().
+ */
+export function getPackageAssetPath(...parts) {
+    return path.join(packageRoot, ...parts);
+}
+/**
+ * Resolves the Kōbō home directory for user data (DB, settings). Respects
+ * KOBO_HOME when set, otherwise defaults to an XDG-compliant location under
+ * ~/.config/kobo. The directory is NOT created here — callers are responsible
+ * for mkdir before writing.
+ *
+ * Dev workflow: `npm run dev` sets KOBO_HOME=./data so local development uses
+ * the repo-relative data/ directory and never touches the user's real home.
+ */
+export function getKoboHome() {
+    if (process.env.KOBO_HOME) {
+        return path.resolve(process.env.KOBO_HOME);
+    }
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) {
+        return path.join(xdgConfigHome, 'kobo');
+    }
+    return path.join(os.homedir(), '.config', 'kobo');
+}
+/**
+ * Same as getKoboHome(), but guarantees the directory exists on disk. Call this
+ * before any filesystem write into the Kōbō home.
+ */
+export function ensureKoboHome() {
+    const dir = getKoboHome();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/**
+ * Absolute path to the SQLite database file under the Kōbō home.
+ */
+export function getDbPath() {
+    return path.join(getKoboHome(), 'kobo.db');
+}
+/**
+ * Absolute path to settings.json under the Kōbō home.
+ */
+export function getSettingsPath() {
+    return path.join(getKoboHome(), 'settings.json');
+}
+/**
+ * Absolute path to skills.json under the Kōbō home — cached list of Claude
+ * Code slash commands discovered from system init events.
+ */
+export function getSkillsPath() {
+    return path.join(getKoboHome(), 'skills.json');
+}
+/**
+ * Absolute path to the compiled MCP server entry (shipped in the published
+ * package as dist/mcp-server/kobo-tasks-server.js). Returns null if not
+ * present — callers (agent-manager) then fall back to the TS source for dev.
+ */
+export function getCompiledMcpServerPath() {
+    const compiled = getPackageAssetPath('dist', 'mcp-server', 'kobo-tasks-server.js');
+    return fs.existsSync(compiled) ? compiled : null;
+}
+/**
+ * Absolute path to the MCP server TypeScript source (used in dev when the
+ * compiled version is absent).
+ */
+export function getMcpServerSourcePath() {
+    return getPackageAssetPath('src', 'mcp-server', 'kobo-tasks-server.ts');
+}
+/**
+ * Absolute path to the built Quasar SPA (src/client/dist/spa). Returns null
+ * if the SPA has not been built yet.
+ */
+export function getClientSpaPath() {
+    const spa = getPackageAssetPath('src', 'client', 'dist', 'spa');
+    return fs.existsSync(spa) ? spa : null;
+}

package/dist/server/utils/process-tracker.js

@@ -0,0 +1,46 @@
+const trackedProcesses = new Map();
+export function registerProcess(id, proc) {
+    trackedProcesses.set(id, proc);
+}
+export function unregisterProcess(id) {
+    trackedProcesses.delete(id);
+}
+export function getProcess(id) {
+    return trackedProcesses.get(id);
+}
+export function getTrackedCount() {
+    return trackedProcesses.size;
+}
+export function killAll() {
+    const procs = [...trackedProcesses.values()];
+    trackedProcesses.clear();
+    const killTimers = procs.map((proc) => {
+        try {
+            proc.kill('SIGTERM');
+        }
+        catch {
+            // Process may already be dead
+        }
+        return setTimeout(() => {
+            try {
+                if (!proc.killed) {
+                    proc.kill('SIGKILL');
+                }
+            }
+            catch {
+                // Ignore
+            }
+        }, 5000);
+    });
+    // Unref timers so they don't keep the process alive
+    killTimers.forEach((t) => {
+        t.unref?.();
+    });
+}
+export function initProcessCleanup() {
+    process.on('exit', killAll);
+    process.on('SIGINT', () => {
+        killAll();
+        process.exit(0);
+    });
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@loicngr/kobo",
+  "version": "0.1.1",
+  "description": "Kōbō — multi-workspace agent manager for Claude Code. Orchestrates isolated git worktrees with dev servers, Notion integration, and MCP tools.",
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "bin": {
+    "kobo": "./dist/server/index.js"
+  },
+  "files": [
+    "dist/",
+    "src/client/dist/spa/",
+    "src/mcp-server/",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "author": {
+    "name": "loicngr",
+    "email": "loicnogier@ik.me",
+    "url": "https://github.com/loicngr"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loicngr/kobo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/loicngr/kobo/issues"
+  },
+  "homepage": "https://github.com/loicngr/kobo#readme",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agent",
+    "mcp",
+    "workspace",
+    "worktree",
+    "hono",
+    "vue",
+    "quasar"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "KOBO_HOME=./data tsx watch src/server/index.ts",
+    "dev:client": "cd src/client && npx quasar dev",
+    "dev:all": "concurrently \"npm run dev\" \"npm run dev:client\"",
+    "build:client": "cd src/client && npx quasar build",
+    "build:server": "npx tsc && chmod +x dist/server/index.js",
+    "build": "npm run build:client && npm run build:server",
+    "start": "node dist/server/index.js",
+    "test": "vitest run --config vitest.config.ts --root .",
+    "test:watch": "vitest --config vitest.config.ts --root .",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.12",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.8.0",
+    "hono": "^4.12.10",
+    "nanoid": "^5.1.7",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.10",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.2",
+    "@types/ws": "^8.18.1",
+    "@vitest/runner": "^4.1.2",
+    "concurrently": "^9.2.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^3.2.4"
+  }
+}