@cleocode/cleo 2026.2.5

package/dist/core/ui/mcp-config.js

@@ -0,0 +1,173 @@
+/**
+ * MCP server configuration for multi-tool auto-detection.
+ *
+ * Detects installed AI coding tools (Claude Code, Cursor, Gemini CLI, etc.)
+ * and generates MCP server configuration entries for each.
+ *
+ * NOTE: For CAAMP-managed MCP config, use @cleocode/caamp imports.
+ * This module provides CLEO-specific detection and configuration logic.
+ *
+ * @task T4454
+ * @epic T4454
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform as osPlatform } from 'node:os';
+/** Known tool keys (ordered). */
+export const MCP_TOOL_KEYS = [
+    'claude-code',
+    'claude-desktop',
+    'cursor',
+    'gemini-cli',
+    'kimi',
+    'windsurf',
+    'goose',
+    'vscode',
+    'zed',
+    'codex',
+];
+const TOOL_DISPLAY_NAMES = {
+    'claude-code': 'Claude Code',
+    'claude-desktop': 'Claude Desktop',
+    'cursor': 'Cursor',
+    'gemini-cli': 'Gemini CLI',
+    'kimi': 'Kimi Code',
+    'windsurf': 'Windsurf',
+    'goose': 'Goose',
+    'vscode': 'VS Code',
+    'zed': 'Zed',
+    'codex': 'Codex',
+};
+const TOOL_FORMATS = {
+    'claude-code': 'json',
+    'claude-desktop': 'json',
+    'cursor': 'json',
+    'gemini-cli': 'json',
+    'kimi': 'json',
+    'windsurf': 'json',
+    'goose': 'json',
+    'vscode': 'json',
+    'zed': 'json',
+    'codex': 'json',
+};
+/** Get global config path for a tool. */
+function getGlobalConfigPath(key) {
+    const home = homedir();
+    const plat = osPlatform();
+    switch (key) {
+        case 'claude-code':
+            return join(home, '.claude', 'settings.json');
+        case 'claude-desktop':
+            if (plat === 'darwin')
+                return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+            if (plat === 'win32')
+                return join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+            return join(home, '.config', 'claude-desktop', 'config.json');
+        case 'cursor':
+            if (plat === 'darwin')
+                return join(home, 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'cursor.mcp', 'mcp.json');
+            return join(home, '.config', 'cursor', 'mcp.json');
+        case 'gemini-cli':
+            return join(home, '.gemini', 'settings.json');
+        case 'vscode':
+            if (plat === 'darwin')
+                return join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+            return join(home, '.config', 'Code', 'User', 'settings.json');
+        default:
+            return join(home, `.${key}`, 'config.json');
+    }
+}
+/** Get project-level config path for a tool. */
+function getProjectConfigPath(key, projectDir) {
+    switch (key) {
+        case 'claude-code': return join(projectDir, '.mcp.json');
+        case 'cursor': return join(projectDir, '.cursor', 'mcp.json');
+        case 'vscode': return join(projectDir, '.vscode', 'mcp.json');
+        default: return join(projectDir, `.${key}`, 'mcp.json');
+    }
+}
+/** Detect if a tool is installed. */
+function detectTool(key) {
+    const globalPath = getGlobalConfigPath(key);
+    // Check global config exists
+    if (existsSync(globalPath))
+        return true;
+    // Check for app bundles on macOS
+    if (osPlatform() === 'darwin') {
+        const appNames = {
+            'claude-desktop': '/Applications/Claude.app',
+            'cursor': '/Applications/Cursor.app',
+            'windsurf': '/Applications/Windsurf.app',
+            'vscode': '/Applications/Visual Studio Code.app',
+            'zed': '/Applications/Zed.app',
+        };
+        const appPath = appNames[key];
+        if (appPath && existsSync(appPath))
+            return true;
+    }
+    return false;
+}
+/** Detect all installed tools. */
+export function detectAllTools(projectDir) {
+    const projDir = projectDir ?? process.cwd();
+    return MCP_TOOL_KEYS.map(key => ({
+        key,
+        displayName: TOOL_DISPLAY_NAMES[key],
+        format: TOOL_FORMATS[key],
+        globalPath: getGlobalConfigPath(key),
+        projectPath: getProjectConfigPath(key, projDir),
+        detected: detectTool(key),
+    }));
+}
+/** Generate an MCP server entry for CLEO. */
+export function generateMCPEntry(cleoPath) {
+    const cleo = cleoPath ?? join(homedir(), '.cleo', 'bin', 'cleo-mcp');
+    return {
+        cleo: {
+            command: cleo,
+            args: ['serve'],
+            env: {},
+        },
+    };
+}
+/** Write MCP config to a tool's config file. */
+export function writeMCPConfig(tool, entry, options = {}) {
+    const configPath = options.project
+        ? getProjectConfigPath(tool, options.projectDir ?? process.cwd())
+        : getGlobalConfigPath(tool);
+    if (options.dryRun) {
+        return { action: 'would_write', path: configPath };
+    }
+    let config = {};
+    if (existsSync(configPath)) {
+        try {
+            config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            // Start fresh if parse fails
+        }
+    }
+    // Merge MCP server entry
+    if (!config.mcpServers)
+        config.mcpServers = {};
+    Object.assign(config.mcpServers, entry);
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    return { action: 'wrote', path: configPath };
+}
+/** Get detection summary for all tools. */
+export function getDetectionSummary(projectDir) {
+    const tools = detectAllTools(projectDir);
+    const detected = tools.filter(t => t.detected);
+    const notDetected = tools.filter(t => !t.detected);
+    return {
+        total: tools.length,
+        detected: detected.length,
+        notDetected: notDetected.length,
+        tools: tools.map(t => ({
+            key: t.key,
+            name: t.displayName,
+            detected: t.detected,
+        })),
+    };
+}
+//# sourceMappingURL=mcp-config.js.map

package/dist/core/ui/mcp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-config.js","sourceRoot":"","sources":["../../../src/core/ui/mcp-config.ts"],"names":[],"mappings":"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"}

package/dist/core/ui/version-check.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Project version checking and warning system.
+ * Ported from lib/ui/version-check.sh
+ *
+ * Fast checks that run on every command to warn about outdated projects.
+ * Compares schema versions, CLAUDE.md injection versions, and detects
+ * legacy structure indicators.
+ *
+ * @task T4552
+ * @epic T4545
+ */
+import type { DataAccessor } from '../../store/data-accessor.js';
+/** Version check result. */
+export interface VersionCheckResult {
+    needsUpdate: boolean;
+    warnings: string[];
+}
+/**
+ * Check if a project needs updates.
+ * Returns warnings for outdated schemas, injections, or legacy structures.
+ * @task T4552
+ */
+export declare function checkProjectNeedsUpdate(projectDir?: string, accessor?: DataAccessor): Promise<VersionCheckResult>;
+/**
+ * Show version warnings if applicable (call before command execution).
+ * Respects skip commands and CLEO_SKIP_VERSION_CHECK env var.
+ * Outputs warnings to stderr so they don't interfere with JSON output.
+ * @task T4552
+ */
+export declare function showVersionWarnings(command?: string): Promise<string[]>;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/core/ui/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../../src/core/ui/version-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAQjE,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,GAAE,MAAY,EACxB,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA+E7B;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAqBnB"}

package/dist/core/ui/version-check.js

@@ -0,0 +1,121 @@
+/**
+ * Project version checking and warning system.
+ * Ported from lib/ui/version-check.sh
+ *
+ * Fast checks that run on every command to warn about outdated projects.
+ * Compares schema versions, CLAUDE.md injection versions, and detects
+ * legacy structure indicators.
+ *
+ * @task T4552
+ * @epic T4545
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCleoHome } from '../paths.js';
+import { readJson } from '../../store/json.js';
+/** Commands that handle their own version checks (skip warnings). */
+const VERSION_CHECK_SKIP_COMMANDS = new Set([
+    'upgrade', 'migrate', 'init', 'validate', 'help', 'version',
+    '--help', '-h', '--version', '-v',
+]);
+/**
+ * Check if a project needs updates.
+ * Returns warnings for outdated schemas, injections, or legacy structures.
+ * @task T4552
+ */
+export async function checkProjectNeedsUpdate(projectDir = '.', accessor) {
+    const warnings = [];
+    const todoFile = join(projectDir, '.cleo', 'todo.json');
+    const claudeMd = join(projectDir, 'CLAUDE.md');
+    // Not a cleo project
+    if (!existsSync(todoFile)) {
+        return { needsUpdate: false, warnings: [] };
+    }
+    // Check schema version
+    const todoData = accessor
+        ? (await accessor.loadTodoFile())
+        : await readJson(todoFile);
+    if (todoData) {
+        const meta = todoData._meta;
+        const currentVersion = meta?.schemaVersion;
+        if (!currentVersion) {
+            warnings.push('Missing ._meta.schemaVersion. Run: cleo upgrade');
+        }
+        else {
+            // Check for legacy structure indicators
+            const hasTopLevelPhases = 'phases' in todoData;
+            const projectField = todoData.project;
+            const projectIsString = typeof projectField === 'string';
+            if (hasTopLevelPhases || projectIsString) {
+                warnings.push('Schema has legacy structure. Run: cleo upgrade');
+            }
+            else {
+                // Get expected version from schema file
+                const schemaDir = process.env['SCHEMA_DIR'] ?? join(getCleoHome(), 'schemas');
+                const schemaPath = join(schemaDir, 'todo.schema.json');
+                if (existsSync(schemaPath)) {
+                    try {
+                        const schemaContent = readFileSync(schemaPath, 'utf-8');
+                        const schema = JSON.parse(schemaContent);
+                        const expectedVersion = schema.schemaVersion;
+                        if (expectedVersion && currentVersion !== expectedVersion) {
+                            warnings.push(`Schema outdated (${currentVersion} → ${expectedVersion}). Run: cleo upgrade`);
+                        }
+                    }
+                    catch {
+                        // Schema read failure is non-fatal
+                    }
+                }
+            }
+        }
+    }
+    // Check CLAUDE.md injection version
+    if (existsSync(claudeMd)) {
+        try {
+            const claudeContent = readFileSync(claudeMd, 'utf-8');
+            const versionMatch = claudeContent.match(/CLEO:START v(\d+\.\d+\.\d+)/);
+            const injectionVersion = versionMatch?.[1];
+            if (injectionVersion) {
+                const versionFilePath = join(getCleoHome(), 'VERSION');
+                if (existsSync(versionFilePath)) {
+                    const installedVersion = readFileSync(versionFilePath, 'utf-8').trim();
+                    if (injectionVersion !== installedVersion) {
+                        warnings.push(`CLAUDE.md outdated (${injectionVersion} → ${installedVersion}). Run: cleo upgrade`);
+                    }
+                }
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    return {
+        needsUpdate: warnings.length > 0,
+        warnings,
+    };
+}
+/**
+ * Show version warnings if applicable (call before command execution).
+ * Respects skip commands and CLEO_SKIP_VERSION_CHECK env var.
+ * Outputs warnings to stderr so they don't interfere with JSON output.
+ * @task T4552
+ */
+export async function showVersionWarnings(command) {
+    // Skip for commands that handle their own checks
+    if (command && VERSION_CHECK_SKIP_COMMANDS.has(command)) {
+        return [];
+    }
+    // Skip if env var is set
+    if (process.env['CLEO_SKIP_VERSION_CHECK']) {
+        return [];
+    }
+    const result = await checkProjectNeedsUpdate('.');
+    // Output warnings to stderr
+    if (result.warnings.length > 0) {
+        for (const warning of result.warnings) {
+            process.stderr.write(`[WARN] ${warning}\n`);
+        }
+    }
+    return result.warnings;
+}
+//# sourceMappingURL=version-check.js.map

package/dist/core/ui/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../../src/core/ui/version-check.ts"],"names":[],"mappings":"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"}

package/dist/core/upgrade.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Core upgrade logic - unified project maintenance.
+ *
+ * Handles:
+ *   1. Storage engine migration (JSON → SQLite)
+ *   2. Schema version upgrades
+ *   3. Structural repairs (checksums, missing fields)
+ *   4. Global ~/.cleo data migration
+ *
+ * Both CLI and MCP delegate here (shared-core pattern).
+ *
+ * @task T4699
+ * @epic T4454
+ */
+/** A single upgrade action with status. */
+export interface UpgradeAction {
+    action: string;
+    status: 'applied' | 'skipped' | 'preview' | 'error';
+    details: string;
+    fix?: string;
+}
+/** Full upgrade result. */
+export interface UpgradeResult {
+    success: boolean;
+    upToDate: boolean;
+    dryRun: boolean;
+    actions: UpgradeAction[];
+    applied: number;
+    errors: string[];
+    /** Storage migration sub-result (if migration was triggered). */
+    storageMigration?: {
+        migrated: boolean;
+        tasksImported: number;
+        archivedImported: number;
+        sessionsImported: number;
+        warnings: string[];
+    };
+}
+/**
+ * Run a full upgrade pass on the project .cleo/ directory.
+ *
+ * Steps:
+ *   1. Pre-flight storage check (JSON → SQLite)
+ *   2. If migration needed and not dry-run, run auto-migration with backup
+ *   3. Schema version checks on JSON files
+ *   4. Structural repairs (checksums, missing fields)
+ *
+ * @param options.dryRun  Preview changes without applying
+ * @param options.includeGlobal  Also check global ~/.cleo
+ * @param options.autoMigrate  Auto-migrate storage if needed (default: true)
+ * @param options.cwd  Project directory override
+ */
+export declare function runUpgrade(options?: {
+    dryRun?: boolean;
+    includeGlobal?: boolean;
+    autoMigrate?: boolean;
+    cwd?: string;
+}): Promise<UpgradeResult>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/core/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/core/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiBH,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2BAA2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,OAAO,GAAE;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GAAG,OAAO,CAAC,aAAa,CAAC,CAqmB9B"}