@phnx-labs/agents-cli 1.14.2 → 1.14.4

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;

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

@@ -0,0 +1,43 @@
+/**
+ * Rules resource handler.
+ *
+ * Rules are .md files in `<repo>/rules/subrules/` directories that get composed
+ * into the agent's instructions file (AGENTS.md -> CLAUDE.md/GEMINI.md/etc).
+ *
+ * Layer resolution: project > user > extras > system
+ * - Same-named subrule at higher layer wins (override)
+ * - All unique subrules across layers are unioned
+ */
+import type { Layer, ResolvedItem, ResourceHandler } from './types.js';
+/** A rule item is a subrule markdown fragment. */
+export interface RuleItem {
+    /** The subrule name (without .md extension). */
+    name: string;
+    /** The full content of the rule file. */
+    content: string;
+}
+/** Layer directory entry for rules resolution. */
+export interface RulesLayerDir {
+    layer: Layer;
+    dir: string;
+}
+/**
+ * List subrule markdown files in a directory.
+ * Returns names without the .md extension.
+ */
+export declare function listSubrulesInDir(subrulesDir: string): string[];
+/**
+ * Get layer directories for rules resolution using production paths.
+ */
+export declare function getLayerDirs(cwd?: string): RulesLayerDir[];
+/**
+ * List all rules from the given layer directories.
+ * Higher layers win on name collision.
+ */
+export declare function listAllRules(layers: RulesLayerDir[]): ResolvedItem<RuleItem>[];
+/**
+ * Resolve a single rule by name from the given layer directories.
+ * Higher layers win.
+ */
+export declare function resolveRule(name: string, layers: RulesLayerDir[]): ResolvedItem<RuleItem> | null;
+export declare const RulesHandler: ResourceHandler<RuleItem>;

package/dist/lib/resources/rules.js

@@ -0,0 +1,146 @@
+/**
+ * Rules resource handler.
+ *
+ * Rules are .md files in `<repo>/rules/subrules/` directories that get composed
+ * into the agent's instructions file (AGENTS.md -> CLAUDE.md/GEMINI.md/etc).
+ *
+ * Layer resolution: project > user > extras > system
+ * - Same-named subrule at higher layer wins (override)
+ * - All unique subrules across layers are unioned
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getSystemRulesDir, getUserRulesDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+const SUBRULES_DIR = 'subrules';
+const SUBRULES_README = 'README.md';
+/**
+ * List subrule markdown files in a directory.
+ * Returns names without the .md extension.
+ */
+export function listSubrulesInDir(subrulesDir) {
+    if (!fs.existsSync(subrulesDir))
+        return [];
+    try {
+        return fs
+            .readdirSync(subrulesDir)
+            .filter((f) => f.endsWith('.md') && f !== SUBRULES_README)
+            .map((f) => f.slice(0, -3))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get layer directories for rules resolution using production paths.
+ */
+export function getLayerDirs(cwd) {
+    const dirs = [];
+    // Project layer (highest priority)
+    const projectDir = getProjectAgentsDir(cwd);
+    if (projectDir) {
+        const rulesDir = path.join(projectDir, 'rules');
+        if (fs.existsSync(rulesDir)) {
+            dirs.push({ layer: 'project', dir: rulesDir });
+        }
+    }
+    // User layer
+    const userDir = getUserRulesDir();
+    if (fs.existsSync(userDir)) {
+        dirs.push({ layer: 'user', dir: userDir });
+    }
+    // Extra repos (treated as user-level in layering)
+    for (const extra of getEnabledExtraRepos()) {
+        const rulesDir = path.join(extra.dir, 'rules');
+        if (fs.existsSync(rulesDir)) {
+            dirs.push({ layer: 'user', dir: rulesDir });
+        }
+    }
+    // System layer (lowest priority)
+    const systemDir = getSystemRulesDir();
+    if (fs.existsSync(systemDir)) {
+        dirs.push({ layer: 'system', dir: systemDir });
+    }
+    return dirs;
+}
+/**
+ * List all rules from the given layer directories.
+ * Higher layers win on name collision.
+ */
+export function listAllRules(layers) {
+    const seen = new Set();
+    const results = [];
+    for (const { layer, dir } of layers) {
+        const subrulesDir = path.join(dir, SUBRULES_DIR);
+        for (const name of listSubrulesInDir(subrulesDir)) {
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            const filePath = path.join(subrulesDir, `${name}.md`);
+            let content = '';
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            results.push({
+                name,
+                item: { name, content },
+                layer,
+                path: filePath,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Resolve a single rule by name from the given layer directories.
+ * Higher layers win.
+ */
+export function resolveRule(name, layers) {
+    for (const { layer, dir } of layers) {
+        const filePath = path.join(dir, SUBRULES_DIR, `${name}.md`);
+        if (fs.existsSync(filePath)) {
+            let content = '';
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            return {
+                name,
+                item: { name, content },
+                layer,
+                path: filePath,
+            };
+        }
+    }
+    return null;
+}
+export const RulesHandler = {
+    kind: 'rule',
+    listAll(_agent, cwd) {
+        return listAllRules(getLayerDirs(cwd));
+    },
+    resolve(_agent, name, cwd) {
+        return resolveRule(name, getLayerDirs(cwd));
+    },
+    sync(agent, versionHome, _cwd) {
+        // Rules sync is handled by the compose module and syncResourcesToVersion.
+        // This method ensures the agent config directory exists.
+        // The actual composition and write happens in versions.ts via composeRulesFromState().
+        const targetDir = path.join(versionHome, `.${agent}`);
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+    },
+    format(_agent) {
+        return 'md';
+    },
+    targetDir(agent) {
+        // Rules don't have a target subdirectory - they're written to the instructions file
+        return `.${agent}`;
+    },
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Skills resource handler.
+ *
+ * Skills are directory bundles with a SKILL.md containing YAML frontmatter.
+ * Format is the same for all agents. Resolution order: project > user > system.
+ */
+import type { ResourceHandler } from './types.js';
+import type { SkillMetadata } from '../types.js';
+/**
+ * Layer directory provider for dependency injection in tests.
+ */
+export interface LayerDirProvider {
+    getSystemSkillsDir(): string;
+    getUserSkillsDir(): string;
+    getProjectAgentsDir(cwd?: string): string | null;
+    getEnabledExtraRepos(): Array<{
+        alias: string;
+        dir: string;
+        url: string;
+    }>;
+}
+/** A resolved skill item with parsed metadata. */
+export interface SkillItem {
+    /** Parsed SKILL.md frontmatter metadata. */
+    metadata: SkillMetadata;
+    /** Number of rule files in the skill's rules/ subdirectory. */
+    ruleCount: number;
+    /** Number of additional bundled files (beyond SKILL.md). */
+    fileCount: number;
+}
+/**
+ * Create a SkillsHandler with the given layer directory provider.
+ * Useful for testing with custom directory structures.
+ */
+export declare function createSkillsHandler(provider?: LayerDirProvider): ResourceHandler<SkillItem>;
+/** Default handler using real state module paths. */
+export declare const SkillsHandler: ResourceHandler<SkillItem>;

package/dist/lib/resources/skills.js

@@ -0,0 +1,238 @@
+/**
+ * Skills resource handler.
+ *
+ * Skills are directory bundles with a SKILL.md containing YAML frontmatter.
+ * Format is the same for all agents. Resolution order: project > user > system.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getSystemSkillsDir, getUserSkillsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../state.js';
+/** Default provider uses the real state module. */
+const defaultProvider = {
+    getSystemSkillsDir,
+    getUserSkillsDir,
+    getProjectAgentsDir,
+    getEnabledExtraRepos,
+};
+/**
+ * Parse SKILL.md frontmatter to extract skill metadata.
+ * Returns null if the file doesn't exist or has no valid frontmatter.
+ */
+function parseSkillMetadata(skillDir) {
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(skillMdPath, 'utf-8');
+        const lines = content.split('\n');
+        // Check for YAML frontmatter (required)
+        if (lines[0] === '---') {
+            const endIndex = lines.slice(1).findIndex((l) => l === '---');
+            if (endIndex > 0) {
+                const frontmatter = lines.slice(1, endIndex + 1).join('\n');
+                const parsed = yaml.parse(frontmatter);
+                return {
+                    name: parsed.name || '',
+                    description: parsed.description || '',
+                    author: parsed.author,
+                    version: parsed.version,
+                    license: parsed.license,
+                    keywords: parsed.keywords,
+                };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Count .md files in the skill's rules/ subdirectory.
+ */
+function countSkillRules(skillDir) {
+    const rulesDir = path.join(skillDir, 'rules');
+    if (!fs.existsSync(rulesDir)) {
+        return 0;
+    }
+    try {
+        const files = fs.readdirSync(rulesDir);
+        return files.filter((f) => f.endsWith('.md')).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Count bundled resource files in a skill directory (everything except SKILL.md).
+ */
+function countSkillFiles(skillDir) {
+    if (!fs.existsSync(skillDir))
+        return 0;
+    let count = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile()) {
+                if (dir === skillDir && entry.name === 'SKILL.md')
+                    continue;
+                count++;
+            }
+        }
+    };
+    walk(skillDir);
+    return count;
+}
+/**
+ * List skill directories in a given base path.
+ * Returns array of { name, fullPath } for directories containing SKILL.md.
+ */
+function listSkillsInDir(baseDir) {
+    if (!fs.existsSync(baseDir))
+        return [];
+    const results = [];
+    try {
+        const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const fullPath = path.join(baseDir, entry.name);
+            const skillMdPath = path.join(fullPath, 'SKILL.md');
+            if (fs.existsSync(skillMdPath)) {
+                results.push({ name: entry.name, fullPath });
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return results;
+}
+/**
+ * Get layer directories for skill resolution.
+ */
+function getLayerDirs(cwd, provider = defaultProvider) {
+    const layers = [];
+    // Project layer
+    const projectDir = cwd ? provider.getProjectAgentsDir(cwd) : null;
+    if (projectDir) {
+        layers.push({ layer: 'project', dir: path.join(projectDir, 'skills') });
+    }
+    // User layer
+    layers.push({ layer: 'user', dir: provider.getUserSkillsDir() });
+    // Extra repos (treated as user layer since they're user-configured)
+    for (const extra of provider.getEnabledExtraRepos()) {
+        layers.push({ layer: 'user', dir: path.join(extra.dir, 'skills') });
+    }
+    // System layer
+    layers.push({ layer: 'system', dir: provider.getSystemSkillsDir() });
+    return layers;
+}
+/**
+ * Create a SkillsHandler with the given layer directory provider.
+ * Useful for testing with custom directory structures.
+ */
+export function createSkillsHandler(provider = defaultProvider) {
+    return {
+        kind: 'skill',
+        listAll(_agent, cwd) {
+            const seen = new Map();
+            const layers = getLayerDirs(cwd, provider);
+            // Process in order: project > user > system
+            // First occurrence wins (higher layer takes precedence)
+            for (const { layer, dir } of layers) {
+                const skills = listSkillsInDir(dir);
+                for (const { name, fullPath } of skills) {
+                    if (seen.has(name))
+                        continue; // Higher layer already has this skill
+                    const metadata = parseSkillMetadata(fullPath);
+                    if (!metadata)
+                        continue; // Skip invalid skills
+                    seen.set(name, {
+                        name,
+                        item: {
+                            metadata,
+                            ruleCount: countSkillRules(fullPath),
+                            fileCount: countSkillFiles(fullPath),
+                        },
+                        layer,
+                        path: fullPath,
+                    });
+                }
+            }
+            return Array.from(seen.values()).sort((a, b) => a.name.localeCompare(b.name));
+        },
+        resolve(_agent, name, cwd) {
+            const layers = getLayerDirs(cwd, provider);
+            for (const { layer, dir } of layers) {
+                const skillPath = path.join(dir, name);
+                const skillMdPath = path.join(skillPath, 'SKILL.md');
+                if (fs.existsSync(skillMdPath)) {
+                    const metadata = parseSkillMetadata(skillPath);
+                    if (!metadata)
+                        continue;
+                    return {
+                        name,
+                        item: {
+                            metadata,
+                            ruleCount: countSkillRules(skillPath),
+                            fileCount: countSkillFiles(skillPath),
+                        },
+                        layer,
+                        path: skillPath,
+                    };
+                }
+            }
+            return null;
+        },
+        sync(agent, versionHome, cwd) {
+            const targetDir = path.join(versionHome, `.${agent}`, 'skills');
+            // Ensure target directory exists
+            if (!fs.existsSync(targetDir)) {
+                fs.mkdirSync(targetDir, { recursive: true });
+            }
+            const resolved = this.listAll(agent, cwd);
+            for (const skill of resolved) {
+                const targetPath = path.join(targetDir, skill.name);
+                // Remove existing if present
+                if (fs.existsSync(targetPath) || fs.lstatSync(targetPath, { throwIfNoEntry: false })) {
+                    try {
+                        fs.rmSync(targetPath, { recursive: true, force: true });
+                    }
+                    catch {
+                        // Ignore removal errors
+                    }
+                }
+                // Copy skill directory
+                try {
+                    fs.cpSync(skill.path, targetPath, { recursive: true });
+                }
+                catch {
+                    // Ignore copy errors
+                }
+            }
+        },
+        format(_agent) {
+            return 'md';
+        },
+        targetDir(agent) {
+            return `.${agent}/skills`;
+        },
+    };
+}
+/** Default handler using real state module paths. */
+export const SkillsHandler = createSkillsHandler();

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

@@ -0,0 +1,46 @@
+/**
+ * Subagents resource handler.
+ *
+ * Subagents are YAML files stored in subagents/ directories across layers.
+ * Format is the same for all agents. Resolution order: project > user > system.
+ */
+import type { AgentId, ResolvedItem, ResourceHandler } from './types.js';
+/** Parsed content of a subagent YAML file. */
+export interface SubagentItem {
+    name: string;
+    description: string;
+    model?: string;
+    /** Hex color for UI display. */
+    color?: string;
+    /** Additional agent-specific config. */
+    config?: Record<string, unknown>;
+}
+export declare class SubagentsHandler implements ResourceHandler<SubagentItem> {
+    readonly kind: "subagent";
+    /**
+     * List all subagents across layers, with higher layer winning on name conflict.
+     * Returns a union of all subagents, deduplicated by name.
+     */
+    listAll(_agent: AgentId, cwd?: string): ResolvedItem<SubagentItem>[];
+    /**
+     * Resolve a single subagent by name.
+     * Returns the winning layer's version, or null if not found.
+     */
+    resolve(_agent: AgentId, name: string, cwd?: string): ResolvedItem<SubagentItem> | null;
+    /**
+     * Sync resolved subagents to the agent's version home directory.
+     * Copies YAML files to the target directory.
+     */
+    sync(agent: AgentId, versionHome: string, cwd?: string): void;
+    /**
+     * Get the file format this resource uses for a given agent.
+     * Subagents always use YAML format.
+     */
+    format(_agent: AgentId): 'md' | 'toml' | 'json' | 'yaml';
+    /**
+     * Get the target directory name in the agent's version home.
+     */
+    targetDir(_agent: AgentId): string;
+}
+/** Singleton instance of the SubagentsHandler. */
+export declare const subagentsHandler: SubagentsHandler;