@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/resources/commands.js

@@ -1,211 +0,0 @@
-/**
- * Commands resource handler.
- *
- * Commands are slash-command definitions stored as .md files (Claude/Codex/Cursor/OpenCode)
- * or .toml files (Gemini). This handler resolves commands across layers (project > user > system),
- * handles format conversion during sync, and provides consistent list/resolve/sync behavior.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from '../state.js';
-import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from '../agents.js';
-import { markdownToToml } from '../convert.js';
-/**
- * Get the commands directory for a given layer root.
- */
-function getCommandsDirForRoot(root) {
-    return path.join(root, 'commands');
-}
-/**
- * Parse a command file and extract metadata.
- */
-function parseCommandFile(filePath) {
-    if (!fs.existsSync(filePath))
-        return null;
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const format = filePath.endsWith('.toml') ? 'toml' : 'md';
-        const name = path.basename(filePath).replace(/\.(md|toml)$/, '');
-        let description = '';
-        if (format === 'md') {
-            // Parse YAML frontmatter for description
-            const lines = content.split('\n');
-            if (lines[0] === '---') {
-                const endIndex = lines.slice(1).findIndex((l) => l === '---');
-                if (endIndex > 0) {
-                    const frontmatter = lines.slice(1, endIndex + 1).join('\n');
-                    const descMatch = frontmatter.match(/description:\s*(.+)/i);
-                    if (descMatch)
-                        description = descMatch[1].trim();
-                }
-            }
-        }
-        else {
-            // Parse TOML for description
-            const descMatch = content.match(/description\s*=\s*"([^"]+)"/);
-            if (descMatch)
-                description = descMatch[1];
-        }
-        return { name, description, content, format };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * List command files in a directory.
- */
-function listCommandsInDir(dir) {
-    if (!fs.existsSync(dir))
-        return [];
-    try {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        const commands = [];
-        for (const entry of entries) {
-            if (entry.isFile()) {
-                if (entry.name.endsWith('.md')) {
-                    commands.push({
-                        name: entry.name.replace('.md', ''),
-                        path: path.join(dir, entry.name),
-                        format: 'md',
-                    });
-                }
-                else if (entry.name.endsWith('.toml')) {
-                    commands.push({
-                        name: entry.name.replace('.toml', ''),
-                        path: path.join(dir, entry.name),
-                        format: 'toml',
-                    });
-                }
-            }
-        }
-        return commands;
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Commands resource handler implementing ResourceHandler<CommandItem>.
- */
-export class CommandsHandler {
-    kind = 'command';
-    /**
-     * List all commands across layers, with higher layer winning on name conflict.
-     * Returns a union of all commands, deduplicated by name.
-     */
-    listAll(agent, cwd) {
-        const seen = new Set();
-        const results = [];
-        const projectDir = getProjectAgentsDir(cwd);
-        const extraRepos = getEnabledExtraRepos();
-        // Build layer roots in precedence order: project > user > system > extras
-        const roots = [];
-        if (projectDir) {
-            roots.push({ dir: getCommandsDirForRoot(projectDir), layer: 'project' });
-        }
-        roots.push({ dir: getCommandsDirForRoot(getUserAgentsDir()), layer: 'user' });
-        roots.push({ dir: getCommandsDirForRoot(getSystemAgentsDir()), layer: 'system' });
-        for (const extra of extraRepos) {
-            roots.push({ dir: getCommandsDirForRoot(extra.dir), layer: 'system' });
-        }
-        for (const { dir, layer } of roots) {
-            const commands = listCommandsInDir(dir);
-            for (const cmd of commands) {
-                if (seen.has(cmd.name))
-                    continue;
-                seen.add(cmd.name);
-                const item = parseCommandFile(cmd.path);
-                if (item) {
-                    results.push({
-                        name: cmd.name,
-                        item,
-                        layer,
-                        path: cmd.path,
-                    });
-                }
-            }
-        }
-        return results;
-    }
-    /**
-     * Resolve a single command by name.
-     * Returns the winning layer's version, or null if not found.
-     */
-    resolve(agent, name, cwd) {
-        const projectDir = getProjectAgentsDir(cwd);
-        const extraRepos = getEnabledExtraRepos();
-        // Build candidate paths in precedence order
-        const candidates = [];
-        if (projectDir) {
-            candidates.push({ dir: getCommandsDirForRoot(projectDir), layer: 'project' });
-        }
-        candidates.push({ dir: getCommandsDirForRoot(getUserAgentsDir()), layer: 'user' });
-        candidates.push({ dir: getCommandsDirForRoot(getSystemAgentsDir()), layer: 'system' });
-        for (const extra of extraRepos) {
-            candidates.push({ dir: getCommandsDirForRoot(extra.dir), layer: 'system' });
-        }
-        for (const { dir, layer } of candidates) {
-            // Try .md first, then .toml
-            for (const ext of ['.md', '.toml']) {
-                const filePath = path.join(dir, `${name}${ext}`);
-                const item = parseCommandFile(filePath);
-                if (item) {
-                    return { name, item, layer, path: filePath };
-                }
-            }
-        }
-        return null;
-    }
-    /**
-     * Sync resolved commands to the agent's version home directory.
-     * Copies/transforms commands as needed for the agent's expected format.
-     */
-    sync(agent, versionHome, cwd) {
-        if (isAgentHardDeprecated(agent)) {
-            return;
-        }
-        const agentConfig = AGENTS[agent];
-        const targetFormat = this.format(agent);
-        const targetDir = path.join(versionHome, agentConfigDirName(agent), this.targetDir(agent));
-        // Ensure target directory exists
-        fs.mkdirSync(targetDir, { recursive: true });
-        // Get all resolved commands
-        const commands = this.listAll(agent, cwd);
-        for (const resolved of commands) {
-            const ext = targetFormat === 'toml' ? '.toml' : '.md';
-            const targetPath = path.join(targetDir, `${resolved.name}${ext}`);
-            // Convert format if needed
-            if (targetFormat === 'toml' && resolved.item.format === 'md') {
-                // Convert markdown to TOML
-                const tomlContent = markdownToToml(resolved.name, resolved.item.content);
-                fs.writeFileSync(targetPath, tomlContent, 'utf-8');
-            }
-            else if (targetFormat === 'md' && resolved.item.format === 'toml') {
-                // For now, copy TOML as-is if target expects md (edge case)
-                // In practice, source commands are always .md
-                fs.copyFileSync(resolved.path, targetPath);
-            }
-            else {
-                // Same format, copy directly
-                fs.copyFileSync(resolved.path, targetPath);
-            }
-        }
-    }
-    /**
-     * Get the file format this resource uses for a given agent.
-     */
-    format(agent) {
-        const agentConfig = AGENTS[agent];
-        return agentConfig.format === 'toml' ? 'toml' : 'md';
-    }
-    /**
-     * Get the target directory name in the agent's version home.
-     */
-    targetDir(agent) {
-        const agentConfig = AGENTS[agent];
-        return agentConfig.commandsSubdir || 'commands';
-    }
-}
-/** Singleton instance of the commands handler. */
-export const commandsHandler = new CommandsHandler();

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

@@ -1,16 +0,0 @@
-/**
- * HooksHandler - ResourceHandler implementation for hooks.
- *
- * Hook declarations live in:
- *   - System: ~/.agents/.system/hooks.yaml (npm-shipped defaults)
- *   - User:   `hooks:` section of ~/.agents/agents.yaml
- *   - Project: <project>/.agents/hooks.yaml
- *
- * Resolution: project > user > system (higher layer wins on name conflict).
- * Non-conflicting hooks from all layers are unioned together.
- */
-import type { ResourceHandler } from './types.js';
-import type { ManifestHook } from '../types.js';
-export type HookItem = ManifestHook;
-export declare const HooksHandler: ResourceHandler<HookItem>;
-export default HooksHandler;

package/dist/lib/resources/hooks.js

@@ -1,153 +0,0 @@
-/**
- * HooksHandler - ResourceHandler implementation for hooks.
- *
- * Hook declarations live in:
- *   - System: ~/.agents/.system/hooks.yaml (npm-shipped defaults)
- *   - User:   `hooks:` section of ~/.agents/agents.yaml
- *   - Project: <project>/.agents/hooks.yaml
- *
- * Resolution: project > user > system (higher layer wins on name conflict).
- * Non-conflicting hooks from all layers are unioned together.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'yaml';
-import { getSystemAgentsDir, getUserAgentsDir, getProjectAgentsDir, } from '../state.js';
-/**
- * Get the hook manifest path for a layer dir. The user layer reads from
- * agents.yaml (hooks: section) since that's where user hooks now live.
- * Other layers continue to use a standalone hooks.yaml.
- */
-function getHooksYamlPath(layerDir) {
-    if (layerDir === getUserAgentsDir()) {
-        return path.join(layerDir, 'agents.yaml');
-    }
-    return path.join(layerDir, 'hooks.yaml');
-}
-/**
- * Parse hooks for a layer directory.
- * - User layer: read `hooks:` section from agents.yaml.
- * - System / project layer: read top-level map from hooks.yaml.
- * Returns empty object if file doesn't exist or is invalid.
- */
-function parseHooksYaml(dir) {
-    const manifestPath = getHooksYamlPath(dir);
-    if (!fs.existsSync(manifestPath)) {
-        return {};
-    }
-    try {
-        const content = fs.readFileSync(manifestPath, 'utf-8');
-        const parsed = yaml.parse(content);
-        if (!parsed)
-            return {};
-        if (dir === getUserAgentsDir()) {
-            const hooks = parsed.hooks;
-            return (hooks && typeof hooks === 'object') ? hooks : {};
-        }
-        return parsed;
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Get layer directories for hook resolution.
- */
-function getLayerDirs(cwd) {
-    return {
-        system: getSystemAgentsDir(),
-        user: getUserAgentsDir(),
-        project: cwd ? getProjectAgentsDir(cwd) : null,
-        extra: [],
-    };
-}
-export const HooksHandler = {
-    kind: 'hook',
-    /**
-     * List all hooks across layers, with higher layer winning on name conflict.
-     * Returns a union of all hooks, deduplicated by name.
-     */
-    listAll(agent, cwd) {
-        const layers = getLayerDirs(cwd);
-        const result = new Map();
-        // Process in precedence order: system first (lowest), then user, then project (highest)
-        const layerOrder = [
-            { layer: 'system', dir: layers.system },
-            { layer: 'user', dir: layers.user },
-            { layer: 'project', dir: layers.project },
-        ];
-        for (const { layer, dir } of layerOrder) {
-            if (!dir)
-                continue;
-            const hooks = parseHooksYaml(dir);
-            for (const [name, hook] of Object.entries(hooks)) {
-                // Skip disabled hooks
-                if (hook.enabled === false) {
-                    result.delete(name);
-                    continue;
-                }
-                result.set(name, {
-                    name,
-                    item: hook,
-                    layer,
-                    path: getHooksYamlPath(dir),
-                });
-            }
-        }
-        return Array.from(result.values()).sort((a, b) => a.name.localeCompare(b.name));
-    },
-    /**
-     * Resolve a single hook by name.
-     * Returns the winning layer's version, or null if not found.
-     */
-    resolve(agent, name, cwd) {
-        const layers = getLayerDirs(cwd);
-        // Check in reverse precedence order: project first (highest), then user, then system
-        const layerOrder = [
-            { layer: 'project', dir: layers.project },
-            { layer: 'user', dir: layers.user },
-            { layer: 'system', dir: layers.system },
-        ];
-        for (const { layer, dir } of layerOrder) {
-            if (!dir)
-                continue;
-            const hooks = parseHooksYaml(dir);
-            const hook = hooks[name];
-            if (hook) {
-                // If this layer disables the hook, return null (disabled trumps lower layers)
-                if (hook.enabled === false) {
-                    return null;
-                }
-                return {
-                    name,
-                    item: hook,
-                    layer,
-                    path: getHooksYamlPath(dir),
-                };
-            }
-        }
-        return null;
-    },
-    /**
-     * Sync resolved hooks to the agent's version home directory.
-     * Note: Actual hook registration is handled by registerHooksToSettings in hooks.ts.
-     * This method is a no-op placeholder for the interface contract.
-     */
-    sync(_agent, _versionHome, _cwd) {
-        // Hook syncing is done via registerHooksToSettings in the main hooks.ts module.
-        // This handler only provides resolution; registration is a separate concern.
-    },
-    /**
-     * Hooks use YAML format across all agents.
-     */
-    format(_agent) {
-        return 'yaml';
-    },
-    /**
-     * Hooks are stored in the hooks directory.
-     */
-    targetDir(_agent) {
-        return 'hooks';
-    },
-};
-export default HooksHandler;

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

@@ -1,34 +0,0 @@
-/**
- * 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 type { AgentId, ResourceHandler } from './types.js';
-/**
- * MCP server item as stored in mcp/*.yaml files.
- */
-export interface McpItem {
-    name: string;
-    transport: 'stdio' | 'http' | 'sse';
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-    url?: string;
-    headers?: Record<string, string>;
-}
-/**
- * Get the config file path for MCP for a given agent.
- * Different agents use different config formats and locations.
- */
-export declare function getMcpConfigPath(agent: AgentId, versionHome: string): string | null;
-/**
- * MCP resource handler implementing ResourceHandler<McpItem>.
- */
-export declare const McpHandler: ResourceHandler<McpItem>;
-export default McpHandler;

package/dist/lib/resources/mcp.js

@@ -1,250 +0,0 @@
-/**
- * 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 { capableAgents } from '../capabilities.js';
-import { getProjectMcpConfigPath } from '../agents.js';
-import { writeMcpConfig } from '../mcp.js';
-import { getSystemMcpDir, getUserMcpDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
-/**
- * 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, '.config', 'opencode', 'opencode.jsonc');
-        case 'cursor':
-            return path.join(versionHome, '.cursor', 'mcp.json');
-        case 'openclaw':
-            return path.join(versionHome, '.openclaw', 'openclaw.json');
-        case 'antigravity':
-            // agy nests under ~/.gemini/antigravity-cli/ (shared parent with Gemini, distinct subdir).
-            return path.join(versionHome, '.gemini', 'antigravity-cli', 'mcp_config.json');
-        case 'grok':
-            return path.join(versionHome, '.grok', 'mcp.json');
-        case 'hermes':
-            return path.join(versionHome, '.hermes', 'config.yaml');
-        case 'pi':
-            // omp reads user-scope MCP from ~/.omp/agent/.mcp.json (Claude schema).
-            return path.join(versionHome, '.omp', 'agent', '.mcp.json');
-        case 'muse':
-            return path.join(versionHome, '.config', 'muse', 'settings.json');
-        case 'warp':
-            // Oz reads user-scope MCP from ~/.warp/.mcp.json (Claude schema).
-            return path.join(versionHome, '.warp', '.mcp.json');
-        default:
-            return null;
-    }
-}
-/**
- * Dispatch MCP items to the agent-specific config writer.
- */
-function syncToAgentConfig(agent, configPath, items, mode = 'overwrite') {
-    writeMcpConfig(agent, configPath, items, mode);
-}
-/**
- * MCP resource handler implementing ResourceHandler<McpItem>.
- */
-export const McpHandler = {
-    kind: 'mcp',
-    listAll(agent, cwd) {
-        if (!capableAgents('mcp').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 (!capableAgents('mcp').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 (!capableAgents('mcp').includes(agent)) {
-            return;
-        }
-        const items = this.listAll(agent, cwd);
-        if (items.length === 0) {
-            return;
-        }
-        // Sync resolved MCPs to the version home (user-level agent config).
-        const configPath = getMcpConfigPath(agent, versionHome);
-        if (configPath) {
-            const mcpItems = items.map((r) => r.item);
-            syncToAgentConfig(agent, configPath, mcpItems, 'overwrite');
-        }
-        // Sync project-layer MCPs to the agent's project-level config path so each
-        // agent CLI can discover them alongside its user-level config. Merge so we
-        // do not clobber entries added manually or by the agent's own CLI.
-        const projectAgentsDir = cwd ? getProjectAgentsDir(cwd) : null;
-        if (projectAgentsDir) {
-            const projectItems = items.filter((r) => r.layer === 'project').map((r) => r.item);
-            if (projectItems.length > 0) {
-                const projectConfigPath = getProjectMcpConfigPath(agent, path.dirname(projectAgentsDir));
-                syncToAgentConfig(agent, projectConfigPath, projectItems, 'merge');
-            }
-        }
-    },
-    format(agent) {
-        switch (agent) {
-            case 'codex':
-            case 'grok':
-                return 'toml';
-            case 'hermes':
-                return 'yaml';
-            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/memory.d.ts

@@ -1,15 +0,0 @@
-/**
- * Memory resource handler — knowledge/facts store (not rules/instructions).
- *
- * Canonical source: layered `memory/` dirs under project/user/system agents
- * roots. Sync copies into each capable agent's version home (see memory.ts).
- */
-import type { ResourceHandler } from './types.js';
-export interface MemoryItem {
-    name: string;
-    content: string;
-    summary: string;
-}
-export declare const MemoryHandler: ResourceHandler<MemoryItem>;
-/** Convenience: list fact names for a cwd. */
-export declare function listMemoryNames(cwd?: string): string[];