@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/settings/mcp-config.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MCP Configuration Loader
+ *
+ * Loads MCP server configs from:
+ *   1. Global: ~/.compilr-dev/mcp.json
+ *   2. Per-project: <projectRoot>/.compilr-dev/mcp.json
+ *
+ * Project config overrides global config (by server name).
+ * Format is compatible with Claude Desktop / Gemini CLI.
+ */
+/**
+ * Single MCP server entry in the config file.
+ * If `command` is present → stdio transport.
+ * If `url` is present → HTTP transport.
+ */
+export interface MCPServerEntry {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    disabled?: boolean;
+    timeout?: number;
+}
+/**
+ * Shape of the mcp.json config file.
+ */
+export interface MCPConfigFile {
+    mcpServers: Record<string, MCPServerEntry>;
+}
+/**
+ * Resolved MCP server config ready for MCPManager.
+ * Uses the MCPServerConfig shape from @compilr-dev/agents.
+ */
+export interface ResolvedMCPServer {
+    name: string;
+    transport: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+/**
+ * Get the global MCP config file path.
+ */
+export declare function getMCPConfigPath(): string;
+/**
+ * Get the per-project MCP config file path.
+ */
+export declare function getProjectMCPConfigPath(projectRoot: string): string;
+/**
+ * Load MCP server configs from global and project-level config files.
+ * Project configs override global by server name.
+ *
+ * @param projectRoot - Optional project root for per-project config
+ * @returns Array of resolved MCP server configs
+ */
+export declare function loadMCPConfig(projectRoot?: string): ResolvedMCPServer[];
+/**
+ * Get existing server names from all config files.
+ * Useful for validating uniqueness when adding a new server.
+ */
+export declare function getExistingServerNames(projectRoot?: string): Set<string>;
+/**
+ * Save a new MCP server entry to the config file.
+ *
+ * @param name - Server name (unique identifier)
+ * @param entry - Server configuration entry
+ * @param scope - 'global' or 'project'
+ * @param projectRoot - Required when scope is 'project'
+ */
+export declare function saveMCPServer(name: string, entry: MCPServerEntry, scope: 'global' | 'project', projectRoot?: string): void;

package/dist/settings/mcp-config.js

@@ -0,0 +1,143 @@
+/**
+ * MCP Configuration Loader
+ *
+ * Loads MCP server configs from:
+ *   1. Global: ~/.compilr-dev/mcp.json
+ *   2. Per-project: <projectRoot>/.compilr-dev/mcp.json
+ *
+ * Project config overrides global config (by server name).
+ * Format is compatible with Claude Desktop / Gemini CLI.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import * as path from 'path';
+import { getDataPath } from './paths.js';
+// =============================================================================
+// Config Loading
+// =============================================================================
+/**
+ * Get the global MCP config file path.
+ */
+export function getMCPConfigPath() {
+    return path.join(getDataPath(), 'mcp.json');
+}
+/**
+ * Get the per-project MCP config file path.
+ */
+export function getProjectMCPConfigPath(projectRoot) {
+    return path.join(projectRoot, '.compilr-dev', 'mcp.json');
+}
+/**
+ * Read and parse an mcp.json file. Returns empty servers on any error.
+ */
+function readMCPConfigFile(filePath) {
+    try {
+        if (!existsSync(filePath)) {
+            return {};
+        }
+        const data = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(data);
+        if (parsed.mcpServers && typeof parsed.mcpServers === 'object') {
+            return parsed.mcpServers;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Convert an MCPServerEntry to a ResolvedMCPServer.
+ * Returns null if the entry is invalid (neither command nor url).
+ */
+function resolveEntry(name, entry) {
+    if (entry.disabled) {
+        return null;
+    }
+    if (entry.command) {
+        return {
+            name,
+            transport: 'stdio',
+            command: entry.command,
+            args: entry.args,
+            env: entry.env,
+            cwd: entry.cwd,
+            timeout: entry.timeout,
+        };
+    }
+    if (entry.url) {
+        return {
+            name,
+            transport: 'http',
+            url: entry.url,
+            headers: entry.headers,
+            timeout: entry.timeout,
+        };
+    }
+    // Neither command nor url — invalid entry
+    return null;
+}
+/**
+ * Load MCP server configs from global and project-level config files.
+ * Project configs override global by server name.
+ *
+ * @param projectRoot - Optional project root for per-project config
+ * @returns Array of resolved MCP server configs
+ */
+export function loadMCPConfig(projectRoot) {
+    // 1. Load global config
+    const globalServers = readMCPConfigFile(getMCPConfigPath());
+    // 2. Load project config (overrides global by name)
+    const projectServers = projectRoot
+        ? readMCPConfigFile(getProjectMCPConfigPath(projectRoot))
+        : {};
+    // 3. Merge: project overrides global
+    const merged = { ...globalServers, ...projectServers };
+    // 4. Resolve each entry
+    const resolved = [];
+    for (const [name, entry] of Object.entries(merged)) {
+        const server = resolveEntry(name, entry);
+        if (server) {
+            resolved.push(server);
+        }
+    }
+    return resolved;
+}
+/**
+ * Get existing server names from all config files.
+ * Useful for validating uniqueness when adding a new server.
+ */
+export function getExistingServerNames(projectRoot) {
+    const globalServers = readMCPConfigFile(getMCPConfigPath());
+    const projectServers = projectRoot
+        ? readMCPConfigFile(getProjectMCPConfigPath(projectRoot))
+        : {};
+    return new Set([...Object.keys(globalServers), ...Object.keys(projectServers)]);
+}
+/**
+ * Save a new MCP server entry to the config file.
+ *
+ * @param name - Server name (unique identifier)
+ * @param entry - Server configuration entry
+ * @param scope - 'global' or 'project'
+ * @param projectRoot - Required when scope is 'project'
+ */
+export function saveMCPServer(name, entry, scope, projectRoot) {
+    const configPath = scope === 'project' && projectRoot
+        ? getProjectMCPConfigPath(projectRoot)
+        : getMCPConfigPath();
+    // Read existing config (or empty)
+    let config = { mcpServers: {} };
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        config = { mcpServers: parsed.mcpServers ?? {} };
+    }
+    catch {
+        // File doesn't exist or invalid — start fresh
+    }
+    // Add/overwrite server entry
+    config.mcpServers[name] = entry;
+    // Ensure directory exists, write file
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}

package/dist/settings/paths.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Path Configuration Module
+ *
+ * Centralized path configuration with safety guards.
+ * Inspired by ATLAS CLI config/index.ts
+ *
+ * Priority order:
+ * 1. Environment variable (COMPILR_*)
+ * 2. Config file (~/.compilr-dev/settings.json)
+ * 3. Default/derived value
+ */
+export interface PathConfig {
+    workspacePath?: string;
+    projectsPath?: string;
+    dataPath?: string;
+    allowedPaths?: string[];
+    requireProjectMatch?: boolean;
+    deleteProtection?: boolean;
+}
+export interface ResolvedPathConfig {
+    workspacePath: string;
+    projectsPath: string;
+    dataPath: string;
+    allowedPaths: string[];
+    requireProjectMatch: boolean;
+    deleteProtection: boolean;
+}
+/**
+ * Get the data directory (where config, DB, credentials live)
+ * Priority: ENV > config > default
+ */
+export declare function getDataPath(): string;
+/**
+ * Get the workspace root directory
+ * Priority: ENV > config > default
+ */
+export declare function getWorkspacePath(): string;
+/**
+ * Get the projects directory
+ * Priority: ENV > config > derived from workspace
+ */
+export declare function getProjectsPath(): string;
+/**
+ * Get all allowed paths for delete operations
+ */
+export declare function getAllowedDeletePaths(): string[];
+/**
+ * Check if delete protection is enabled (default: true)
+ */
+export declare function isDeleteProtectionEnabled(): boolean;
+/**
+ * Check if project match warning is enabled (default: true)
+ */
+export declare function isProjectMatchRequired(): boolean;
+/**
+ * Get resolved configuration for display
+ */
+export declare function getResolvedPathConfig(): ResolvedPathConfig;
+/**
+ * Set workspace path
+ */
+export declare function setWorkspacePath(p: string): void;
+/**
+ * Set projects path
+ */
+export declare function setProjectsPath(p: string): void;
+/**
+ * Set data path
+ */
+export declare function setDataPath(p: string): void;
+/**
+ * Enable/disable delete protection
+ */
+export declare function setDeleteProtection(enabled: boolean): void;
+/**
+ * Enable/disable project match warning
+ */
+export declare function setProjectMatchRequired(enabled: boolean): void;
+/**
+ * Add an allowed path for delete operations
+ */
+export declare function addAllowedPath(p: string): void;
+/**
+ * Remove an allowed path
+ */
+export declare function removeAllowedPath(p: string): void;
+/**
+ * Clear all custom allowed paths
+ */
+export declare function clearAllowedPaths(): void;
+/**
+ * Get the database file path
+ */
+export declare function getDatabasePath(): string;
+/**
+ * Get the credentials file path
+ */
+export declare function getCredentialsPath(): string;
+/**
+ * Get the settings file path
+ */
+export declare function getSettingsPath(): string;
+/**
+ * Get the sessions directory path (for session checkpointing)
+ */
+export declare function getSessionsPath(): string;
+/**
+ * Ensure data directory exists
+ */
+export declare function ensureDataDirectory(): void;
+/**
+ * Ensure projects directory exists
+ */
+export declare function ensureProjectsDirectory(): void;

package/dist/settings/paths.js

@@ -0,0 +1,270 @@
+/**
+ * Path Configuration Module
+ *
+ * Centralized path configuration with safety guards.
+ * Inspired by ATLAS CLI config/index.ts
+ *
+ * Priority order:
+ * 1. Environment variable (COMPILR_*)
+ * 2. Config file (~/.compilr-dev/settings.json)
+ * 3. Default/derived value
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// =============================================================================
+// Constants
+// =============================================================================
+const CONFIG_DIR = path.join(os.homedir(), '.compilr-dev');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'settings.json');
+const DEFAULT_DATA_PATH = CONFIG_DIR;
+const DEFAULT_WORKSPACE_PATH = os.homedir();
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Load path config from disk
+ */
+function loadPathConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            const data = fs.readFileSync(CONFIG_FILE, 'utf-8');
+            const settings = JSON.parse(data);
+            return {
+                workspacePath: settings.workspacePath,
+                projectsPath: settings.projectsPath,
+                dataPath: settings.dataPath,
+                allowedPaths: settings.allowedPaths,
+                requireProjectMatch: settings.requireProjectMatch,
+                deleteProtection: settings.deleteProtection,
+            };
+        }
+    }
+    catch {
+        // Ignore errors, return empty config
+    }
+    return {};
+}
+/**
+ * Save path config to disk (merges with existing settings)
+ */
+function savePathConfig(pathConfig) {
+    try {
+        let existingSettings = {};
+        if (fs.existsSync(CONFIG_FILE)) {
+            const data = fs.readFileSync(CONFIG_FILE, 'utf-8');
+            existingSettings = JSON.parse(data);
+        }
+        const merged = { ...existingSettings, ...pathConfig };
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.error('Failed to save path config:', error);
+    }
+}
+/**
+ * Expand ~ to home directory and resolve path
+ */
+function expandPath(p) {
+    if (p.startsWith('~/')) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return path.resolve(p);
+}
+// =============================================================================
+// Public API - Getters
+// =============================================================================
+/**
+ * Get the data directory (where config, DB, credentials live)
+ * Priority: ENV > config > default
+ */
+export function getDataPath() {
+    if (process.env.COMPILR_DATA_PATH) {
+        return expandPath(process.env.COMPILR_DATA_PATH);
+    }
+    const config = loadPathConfig();
+    return config.dataPath ? expandPath(config.dataPath) : DEFAULT_DATA_PATH;
+}
+/**
+ * Get the workspace root directory
+ * Priority: ENV > config > default
+ */
+export function getWorkspacePath() {
+    if (process.env.COMPILR_WORKSPACE_PATH) {
+        return expandPath(process.env.COMPILR_WORKSPACE_PATH);
+    }
+    const config = loadPathConfig();
+    return config.workspacePath ? expandPath(config.workspacePath) : DEFAULT_WORKSPACE_PATH;
+}
+/**
+ * Get the projects directory
+ * Priority: ENV > config > derived from workspace
+ */
+export function getProjectsPath() {
+    if (process.env.COMPILR_PROJECTS_PATH) {
+        return expandPath(process.env.COMPILR_PROJECTS_PATH);
+    }
+    const config = loadPathConfig();
+    return config.projectsPath ? expandPath(config.projectsPath) : path.join(getWorkspacePath(), 'projects');
+}
+/**
+ * Get all allowed paths for delete operations
+ */
+export function getAllowedDeletePaths() {
+    const config = loadPathConfig();
+    const paths = [getProjectsPath()];
+    if (config.allowedPaths) {
+        paths.push(...config.allowedPaths.map(expandPath));
+    }
+    return paths.map((p) => path.resolve(p));
+}
+/**
+ * Check if delete protection is enabled (default: true)
+ */
+export function isDeleteProtectionEnabled() {
+    const config = loadPathConfig();
+    return config.deleteProtection ?? true;
+}
+/**
+ * Check if project match warning is enabled (default: true)
+ */
+export function isProjectMatchRequired() {
+    const config = loadPathConfig();
+    return config.requireProjectMatch ?? true;
+}
+/**
+ * Get resolved configuration for display
+ */
+export function getResolvedPathConfig() {
+    const config = loadPathConfig();
+    return {
+        workspacePath: getWorkspacePath(),
+        projectsPath: getProjectsPath(),
+        dataPath: getDataPath(),
+        allowedPaths: config.allowedPaths?.map(expandPath) || [],
+        requireProjectMatch: config.requireProjectMatch ?? true,
+        deleteProtection: config.deleteProtection ?? true,
+    };
+}
+// =============================================================================
+// Public API - Setters
+// =============================================================================
+/**
+ * Set workspace path
+ */
+export function setWorkspacePath(p) {
+    const config = loadPathConfig();
+    config.workspacePath = expandPath(p);
+    savePathConfig(config);
+}
+/**
+ * Set projects path
+ */
+export function setProjectsPath(p) {
+    const config = loadPathConfig();
+    config.projectsPath = expandPath(p);
+    savePathConfig(config);
+}
+/**
+ * Set data path
+ */
+export function setDataPath(p) {
+    const config = loadPathConfig();
+    config.dataPath = expandPath(p);
+    savePathConfig(config);
+}
+/**
+ * Enable/disable delete protection
+ */
+export function setDeleteProtection(enabled) {
+    const config = loadPathConfig();
+    config.deleteProtection = enabled;
+    savePathConfig(config);
+}
+/**
+ * Enable/disable project match warning
+ */
+export function setProjectMatchRequired(enabled) {
+    const config = loadPathConfig();
+    config.requireProjectMatch = enabled;
+    savePathConfig(config);
+}
+/**
+ * Add an allowed path for delete operations
+ */
+export function addAllowedPath(p) {
+    const config = loadPathConfig();
+    const normalized = expandPath(p);
+    if (!config.allowedPaths) {
+        config.allowedPaths = [];
+    }
+    if (!config.allowedPaths.includes(normalized)) {
+        config.allowedPaths.push(normalized);
+        savePathConfig(config);
+    }
+}
+/**
+ * Remove an allowed path
+ */
+export function removeAllowedPath(p) {
+    const config = loadPathConfig();
+    const normalized = expandPath(p);
+    if (config.allowedPaths) {
+        config.allowedPaths = config.allowedPaths.filter((existing) => expandPath(existing) !== normalized);
+        savePathConfig(config);
+    }
+}
+/**
+ * Clear all custom allowed paths
+ */
+export function clearAllowedPaths() {
+    const config = loadPathConfig();
+    config.allowedPaths = [];
+    savePathConfig(config);
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Get the database file path
+ */
+export function getDatabasePath() {
+    return path.join(getDataPath(), 'projects.db');
+}
+/**
+ * Get the credentials file path
+ */
+export function getCredentialsPath() {
+    return path.join(getDataPath(), 'credentials.enc');
+}
+/**
+ * Get the settings file path
+ */
+export function getSettingsPath() {
+    return path.join(getDataPath(), 'settings.json');
+}
+/**
+ * Get the sessions directory path (for session checkpointing)
+ */
+export function getSessionsPath() {
+    return path.join(getDataPath(), 'sessions');
+}
+/**
+ * Ensure data directory exists
+ */
+export function ensureDataDirectory() {
+    const dataPath = getDataPath();
+    if (!fs.existsSync(dataPath)) {
+        fs.mkdirSync(dataPath, { recursive: true });
+    }
+}
+/**
+ * Ensure projects directory exists
+ */
+export function ensureProjectsDirectory() {
+    const projectsPath = getProjectsPath();
+    if (!fs.existsSync(projectsPath)) {
+        fs.mkdirSync(projectsPath, { recursive: true });
+    }
+}

package/dist/shared-handlers.d.ts

@@ -61,3 +61,65 @@ export declare function setOverlayActive(active: boolean): void;
  * Check if an overlay is currently active.
  */
 export declare function isOverlayActive(): boolean;
+export interface DelegateInput {
+    /** Target agent ID (e.g., 'arch', 'dev-1') */
+    agentId: string;
+    /** Task description for the specialist */
+    task: string;
+    /** Optional reason for delegation (shown to user) */
+    reason?: string;
+}
+export interface DelegateResult {
+    /** True if delegation was approved and switch occurred */
+    success: boolean;
+    /** True if user declined the delegation */
+    declined: boolean;
+    /** Error message if delegation failed */
+    error?: string;
+}
+export type DelegateHandler = (input: DelegateInput) => Promise<DelegateResult>;
+/**
+ * Register the delegate handler. Called during app initialization.
+ */
+export declare function registerDelegateHandler(handler: DelegateHandler): void;
+/**
+ * Get the registered delegate handler. Called by the delegate tool.
+ */
+export declare function getDelegateHandler(): DelegateHandler | undefined;
+export interface DelegateBackgroundInput {
+    /** Target specialist agent ID */
+    agentId: string;
+    /** Task description for the specialist */
+    task: string;
+    /** Optional todo index to associate with this delegation */
+    todoIndex?: number;
+    /** What the specialist should produce */
+    expectedOutput?: string;
+}
+export interface DelegateBackgroundResult {
+    /** Unique delegation ID for tracking */
+    delegationId: string;
+    /** Current status: running or queued */
+    status: 'running' | 'queued';
+    /** Error message if delegation failed */
+    error?: string;
+}
+export type DelegateBackgroundHandler = (input: DelegateBackgroundInput) => Promise<DelegateBackgroundResult>;
+/**
+ * Register the delegate_background handler. Called during app initialization.
+ */
+export declare function registerDelegateBackgroundHandler(handler: DelegateBackgroundHandler): void;
+/**
+ * Get the registered delegate_background handler.
+ */
+export declare function getDelegateBackgroundHandler(): DelegateBackgroundHandler | undefined;
+/** Handoff uses the same shape as delegation */
+export type HandoffHandler = (input: DelegateInput) => Promise<DelegateResult>;
+/**
+ * Register the handoff handler. Called during app initialization.
+ */
+export declare function registerHandoffHandler(handler: HandoffHandler): void;
+/**
+ * Get the registered handoff handler. Called by the handoff tool.
+ */
+export declare function getHandoffHandler(): HandoffHandler | undefined;