@phnx-labs/agents-cli 1.14.3 → 1.14.5

package/dist/lib/resources/mcp.js

@@ -0,0 +1,483 @@
+/**
+ * MCP resource handler - lists, resolves, and syncs MCP server configs across layers.
+ *
+ * MCP servers are stored as YAML files in mcp/ directories:
+ *   ~/.agents-system/mcp/   (system)
+ *   ~/.agents/mcp/          (user)
+ *   .agents/mcp/            (project)
+ *
+ * Resolution: project > user > system (higher layer wins on name conflict).
+ * Sync writes into agent-specific config files (settings.json, config.toml, etc).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import * as TOML from 'smol-toml';
+import { getSystemMcpDir, getUserMcpDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+/** Agents from resources/types.ts that support MCP. */
+const MCP_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'cursor', 'opencode', 'openclaw'];
+/**
+ * Parse an MCP YAML file into an McpItem.
+ */
+function parseMcpYaml(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        // Validate required fields
+        if (!parsed.name || !parsed.transport) {
+            return null;
+        }
+        // Validate transport-specific fields
+        if (parsed.transport === 'stdio' && !parsed.command) {
+            return null;
+        }
+        if ((parsed.transport === 'http' || parsed.transport === 'sse') && !parsed.url) {
+            return null;
+        }
+        return {
+            name: parsed.name,
+            transport: parsed.transport,
+            command: parsed.command,
+            args: parsed.args,
+            env: parsed.env,
+            url: parsed.url,
+            headers: parsed.headers,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get layer directories for MCP resolution.
+ */
+function getLayerDirs(cwd) {
+    const dirs = [];
+    // Project layer (highest priority)
+    const projectDir = getProjectAgentsDir(cwd || process.cwd());
+    if (projectDir) {
+        dirs.push({ layer: 'project', dir: path.join(projectDir, 'mcp') });
+    }
+    // User layer
+    dirs.push({ layer: 'user', dir: getUserMcpDir() });
+    // Extra repos (between user and system)
+    for (const { dir } of getEnabledExtraRepos()) {
+        dirs.push({ layer: 'user', dir: path.join(dir, 'mcp') });
+    }
+    // System layer (lowest priority)
+    dirs.push({ layer: 'system', dir: getSystemMcpDir() });
+    return dirs;
+}
+/**
+ * Scan a directory for MCP YAML files.
+ */
+function scanMcpDir(dir) {
+    const results = [];
+    if (!fs.existsSync(dir)) {
+        return results;
+    }
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                continue;
+            const filePath = path.join(dir, entry.name);
+            const item = parseMcpYaml(filePath);
+            if (item) {
+                results.push({ name: item.name, path: filePath, item });
+            }
+        }
+    }
+    catch {
+        // Directory read failed
+    }
+    return results;
+}
+/**
+ * Get the config file path for MCP for a given agent.
+ * Different agents use different config formats and locations.
+ */
+export function getMcpConfigPath(agent, versionHome) {
+    switch (agent) {
+        case 'claude':
+            return path.join(versionHome, '.claude', 'settings.json');
+        case 'codex':
+            return path.join(versionHome, '.codex', 'config.toml');
+        case 'opencode':
+            return path.join(versionHome, '.opencode', 'opencode.jsonc');
+        case 'cursor':
+            return path.join(versionHome, '.cursor', 'mcp.json');
+        case 'gemini':
+            return path.join(versionHome, '.gemini', 'settings.json');
+        case 'openclaw':
+            return path.join(versionHome, '.openclaw', 'openclaw.json');
+        default:
+            return null;
+    }
+}
+/**
+ * Strip JSON comments (for JSONC files).
+ */
+function stripJsonComments(content) {
+    let result = '';
+    let inString = false;
+    let escape = false;
+    let i = 0;
+    while (i < content.length) {
+        const char = content[i];
+        const next = content[i + 1];
+        if (escape) {
+            result += char;
+            escape = false;
+            i++;
+            continue;
+        }
+        if (char === '\\' && inString) {
+            result += char;
+            escape = true;
+            i++;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            result += char;
+            i++;
+            continue;
+        }
+        if (!inString) {
+            if (char === '/' && next === '/') {
+                while (i < content.length && content[i] !== '\n') {
+                    i++;
+                }
+                continue;
+            }
+            if (char === '/' && next === '*') {
+                i += 2;
+                while (i < content.length && !(content[i] === '*' && content[i + 1] === '/')) {
+                    i++;
+                }
+                i += 2;
+                continue;
+            }
+        }
+        result += char;
+        i++;
+    }
+    return result;
+}
+/**
+ * Write MCP servers to Claude settings.json format.
+ */
+function syncToClaudeConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                env: item.env || {},
+            };
+        }
+        else {
+            mcpServers[item.name] = {
+                url: item.url,
+                ...(item.headers && { headers: item.headers }),
+            };
+        }
+    }
+    config.mcpServers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Write MCP servers to Codex config.toml format.
+ */
+function syncToCodexConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                ...(item.env && { env: item.env }),
+            };
+        }
+        // Codex may not support HTTP MCPs
+    }
+    config.mcp_servers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
+}
+/**
+ * Write MCP servers to OpenCode opencode.jsonc format.
+ */
+function syncToOpenCodeConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = stripJsonComments(fs.readFileSync(configPath, 'utf-8'));
+            config = JSON.parse(content);
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcp = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            // OpenCode uses command as array
+            const commandArray = [item.command, ...(item.args || [])];
+            mcp[item.name] = {
+                type: 'local',
+                command: commandArray,
+                ...(item.env && { env: item.env }),
+            };
+        }
+        else {
+            mcp[item.name] = {
+                type: 'remote',
+                url: item.url,
+            };
+        }
+    }
+    config.mcp = mcp;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Write MCP servers to Cursor mcp.json format.
+ */
+function syncToCursorConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                env: item.env || {},
+            };
+        }
+        else {
+            mcpServers[item.name] = {
+                url: item.url,
+            };
+        }
+    }
+    config.mcpServers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Write MCP servers to Gemini settings.json format.
+ */
+function syncToGeminiConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                env: item.env || {},
+            };
+        }
+        else {
+            mcpServers[item.name] = {
+                url: item.url,
+            };
+        }
+    }
+    config.mcpServers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Write MCP servers to OpenClaw openclaw.json format.
+ */
+function syncToOpenClawConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    if (!config.mcp || typeof config.mcp !== 'object') {
+        config.mcp = {};
+    }
+    const servers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            servers[item.name] = {
+                command: item.command,
+                args: item.args,
+                env: item.env,
+            };
+        }
+        else {
+            servers[item.name] = {
+                url: item.url,
+                transport: item.transport,
+            };
+        }
+    }
+    config.mcp.servers = servers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * MCP resource handler implementing ResourceHandler<McpItem>.
+ */
+export const McpHandler = {
+    kind: 'mcp',
+    listAll(agent, cwd) {
+        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+            return [];
+        }
+        const results = new Map();
+        const layerDirs = getLayerDirs(cwd);
+        // Process in reverse order (system first) so higher layers override
+        for (let i = layerDirs.length - 1; i >= 0; i--) {
+            const { layer, dir } = layerDirs[i];
+            const items = scanMcpDir(dir);
+            for (const { name, path: itemPath, item } of items) {
+                results.set(name, {
+                    name,
+                    item,
+                    layer,
+                    path: itemPath,
+                });
+            }
+        }
+        return Array.from(results.values());
+    },
+    resolve(agent, name, cwd) {
+        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+            return null;
+        }
+        const layerDirs = getLayerDirs(cwd);
+        // Check in priority order (project first)
+        for (const { layer, dir } of layerDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            try {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isFile())
+                        continue;
+                    if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
+                        continue;
+                    const filePath = path.join(dir, entry.name);
+                    const item = parseMcpYaml(filePath);
+                    if (item && item.name === name) {
+                        return {
+                            name,
+                            item,
+                            layer,
+                            path: filePath,
+                        };
+                    }
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    },
+    sync(agent, versionHome, cwd) {
+        if (!MCP_CAPABLE_AGENTS.includes(agent)) {
+            return;
+        }
+        const items = this.listAll(agent, cwd);
+        if (items.length === 0) {
+            return;
+        }
+        const configPath = getMcpConfigPath(agent, versionHome);
+        if (!configPath) {
+            return;
+        }
+        const mcpItems = items.map((r) => r.item);
+        switch (agent) {
+            case 'claude':
+                syncToClaudeConfig(configPath, mcpItems);
+                break;
+            case 'codex':
+                syncToCodexConfig(configPath, mcpItems);
+                break;
+            case 'opencode':
+                syncToOpenCodeConfig(configPath, mcpItems);
+                break;
+            case 'cursor':
+                syncToCursorConfig(configPath, mcpItems);
+                break;
+            case 'gemini':
+                syncToGeminiConfig(configPath, mcpItems);
+                break;
+            case 'openclaw':
+                syncToOpenClawConfig(configPath, mcpItems);
+                break;
+        }
+    },
+    format(agent) {
+        switch (agent) {
+            case 'codex':
+                return 'toml';
+            default:
+                return 'json';
+        }
+    },
+    targetDir(_agent) {
+        // MCP doesn't have a target directory - it modifies config files
+        return 'mcp';
+    },
+    configPath(agent, versionHome) {
+        return getMcpConfigPath(agent, versionHome);
+    },
+};
+export default McpHandler;

package/dist/lib/resources/permissions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PermissionsHandler - ResourceHandler implementation for permissions.
+ *
+ * Permissions are stored as YAML files in permissions/ directories at each layer.
+ * Resolution: project > user > system (higher layer wins on name conflict).
+ * Unlike other resources, permissions merge into agent-specific config files
+ * (Claude: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
+ */
+import type { ResourceHandler } from './types.js';
+import type { PermissionSet } from '../types.js';
+export type PermissionItem = PermissionSet;
+export declare const PermissionsHandler: ResourceHandler<PermissionItem>;
+export default PermissionsHandler;

package/dist/lib/resources/permissions.js

@@ -0,0 +1,184 @@
+/**
+ * PermissionsHandler - ResourceHandler implementation for permissions.
+ *
+ * Permissions are stored as YAML files in permissions/ directories at each layer.
+ * Resolution: project > user > system (higher layer wins on name conflict).
+ * Unlike other resources, permissions merge into agent-specific config files
+ * (Claude: settings.json, Codex: config.toml, OpenCode: opencode.jsonc).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getSystemAgentsDir, getUserAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+import { parsePermissionSet, applyPermissionsToVersion, mergePermissionSets, PERMISSIONS_CAPABLE_AGENTS, } from '../permissions.js';
+/**
+ * Get the permissions directory for a given layer root.
+ */
+function getPermissionsDirForRoot(root) {
+    return path.join(root, 'permissions');
+}
+/**
+ * Get layer directories for permission resolution.
+ */
+function getLayerDirs(cwd) {
+    return {
+        system: getSystemAgentsDir(),
+        user: getUserAgentsDir(),
+        project: cwd ? getProjectAgentsDir(cwd) : null,
+        extra: getEnabledExtraRepos().map((e) => e.dir),
+    };
+}
+/**
+ * List permission files in a directory.
+ * Returns only YAML files, stripping the extension for the name.
+ */
+function listPermissionsInDir(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const permissions = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            if (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml')) {
+                permissions.push({
+                    name: entry.name.replace(/\.(yaml|yml)$/, ''),
+                    path: path.join(dir, entry.name),
+                });
+            }
+        }
+        return permissions;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get the config file path for an agent's permissions.
+ */
+function getAgentConfigPath(agent, versionHome) {
+    switch (agent) {
+        case 'claude':
+            return path.join(versionHome, '.claude', 'settings.json');
+        case 'codex':
+            return path.join(versionHome, '.codex', 'config.toml');
+        case 'opencode':
+            return path.join(versionHome, '.opencode', 'opencode.jsonc');
+        default:
+            return null;
+    }
+}
+export const PermissionsHandler = {
+    kind: 'permission',
+    /**
+     * List all permissions across layers, with higher layer winning on name conflict.
+     * Returns a union of all permissions, deduplicated by name.
+     */
+    listAll(agent, cwd) {
+        const layers = getLayerDirs(cwd);
+        const seen = new Set();
+        const results = [];
+        // Build layer roots in precedence order: project > user > system > extras
+        const roots = [];
+        if (layers.project) {
+            roots.push({ dir: getPermissionsDirForRoot(layers.project), layer: 'project' });
+        }
+        roots.push({ dir: getPermissionsDirForRoot(layers.user), layer: 'user' });
+        roots.push({ dir: getPermissionsDirForRoot(layers.system), layer: 'system' });
+        for (const extraDir of layers.extra) {
+            roots.push({ dir: getPermissionsDirForRoot(extraDir), layer: 'system' });
+        }
+        for (const { dir, layer } of roots) {
+            const permissions = listPermissionsInDir(dir);
+            for (const perm of permissions) {
+                if (seen.has(perm.name))
+                    continue;
+                seen.add(perm.name);
+                const item = parsePermissionSet(perm.path);
+                if (item) {
+                    results.push({
+                        name: perm.name,
+                        item,
+                        layer,
+                        path: perm.path,
+                    });
+                }
+            }
+        }
+        return results.sort((a, b) => a.name.localeCompare(b.name));
+    },
+    /**
+     * Resolve a single permission by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(agent, name, cwd) {
+        const layers = getLayerDirs(cwd);
+        // Build candidate paths in precedence order: project > user > system > extras
+        const candidates = [];
+        if (layers.project) {
+            candidates.push({ dir: getPermissionsDirForRoot(layers.project), layer: 'project' });
+        }
+        candidates.push({ dir: getPermissionsDirForRoot(layers.user), layer: 'user' });
+        candidates.push({ dir: getPermissionsDirForRoot(layers.system), layer: 'system' });
+        for (const extraDir of layers.extra) {
+            candidates.push({ dir: getPermissionsDirForRoot(extraDir), layer: 'system' });
+        }
+        for (const { dir, layer } of candidates) {
+            // Try .yaml first, then .yml
+            for (const ext of ['.yaml', '.yml']) {
+                const filePath = path.join(dir, `${name}${ext}`);
+                const item = parsePermissionSet(filePath);
+                if (item) {
+                    return { name, item, layer, path: filePath };
+                }
+            }
+        }
+        return null;
+    },
+    /**
+     * Sync resolved permissions to the agent's version home config file.
+     * Merges all resolved permissions into a single set and applies to the agent's config.
+     */
+    sync(agent, versionHome, cwd) {
+        // Only sync to agents that support permissions
+        if (!PERMISSIONS_CAPABLE_AGENTS.includes(agent)) {
+            return;
+        }
+        const resolved = this.listAll(agent, cwd);
+        if (resolved.length === 0)
+            return;
+        // Merge all permission sets into one
+        let merged = {
+            name: 'merged',
+            description: 'Merged from all layers',
+            allow: [],
+            deny: [],
+        };
+        for (const r of resolved) {
+            merged = mergePermissionSets(merged, r.item);
+        }
+        // Apply to the agent's config file
+        applyPermissionsToVersion(agent, merged, versionHome, true);
+    },
+    /**
+     * Permissions use YAML format.
+     */
+    format(_agent) {
+        return 'yaml';
+    },
+    /**
+     * Permissions directory name.
+     */
+    targetDir(_agent) {
+        return 'permissions';
+    },
+    /**
+     * Return the config file path where permissions are merged.
+     */
+    configPath(agent, versionHome) {
+        return getAgentConfigPath(agent, versionHome);
+    },
+};
+export default PermissionsHandler;