@phnx-labs/agents-cli 1.14.3 → 1.14.5

package/dist/lib/resources/hooks.js

@@ -0,0 +1,136 @@
+/**
+ * HooksHandler - ResourceHandler implementation for hooks.
+ *
+ * Hooks are declared in hooks.yaml at each layer (system, user, project).
+ * 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 hooks.yaml path for a given layer directory.
+ */
+function getHooksYamlPath(layerDir) {
+    return path.join(layerDir, 'hooks.yaml');
+}
+/**
+ * Parse hooks.yaml from a directory.
+ * 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);
+        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/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Unified resource system - exports all handlers and provides a registry.
+ *
+ * Usage:
+ *   import { handlers, getHandler } from './resources/index.js';
+ *   const cmds = handlers.commands.listAll('claude');
+ */
+export * from './types.js';
+export { CommandsHandler, commandsHandler, type CommandItem } from './commands.js';
+export { HooksHandler, type HookItem } from './hooks.js';
+export { SkillsHandler, type SkillItem } from './skills.js';
+export { RulesHandler, type RuleItem } from './rules.js';
+export { McpHandler, getMcpConfigPath, type McpItem } from './mcp.js';
+export { PermissionsHandler, type PermissionItem } from './permissions.js';
+export { SubagentsHandler, subagentsHandler, type SubagentItem } from './subagents.js';
+import type { ResourceKind, ResourceHandler } from './types.js';
+/** All resource handlers keyed by kind. */
+export declare const handlers: {
+    readonly command: import("./commands.js").CommandsHandler;
+    readonly commands: import("./commands.js").CommandsHandler;
+    readonly hook: ResourceHandler<import("../types.js").ManifestHook>;
+    readonly hooks: ResourceHandler<import("../types.js").ManifestHook>;
+    readonly skill: ResourceHandler<import("./skills.js").SkillItem>;
+    readonly skills: ResourceHandler<import("./skills.js").SkillItem>;
+    readonly rule: ResourceHandler<import("./rules.js").RuleItem>;
+    readonly rules: ResourceHandler<import("./rules.js").RuleItem>;
+    readonly mcp: ResourceHandler<import("./mcp.js").McpItem>;
+    readonly permission: ResourceHandler<import("../types.js").PermissionSet>;
+    readonly permissions: ResourceHandler<import("../types.js").PermissionSet>;
+    readonly subagent: import("./subagents.js").SubagentsHandler;
+    readonly subagents: import("./subagents.js").SubagentsHandler;
+};
+/** Get a handler by resource kind. */
+export declare function getHandler(kind: ResourceKind): ResourceHandler<unknown> | null;
+/** All resource kinds. */
+export declare const RESOURCE_KINDS: ResourceKind[];

package/dist/lib/resources/index.js

@@ -0,0 +1,69 @@
+/**
+ * Unified resource system - exports all handlers and provides a registry.
+ *
+ * Usage:
+ *   import { handlers, getHandler } from './resources/index.js';
+ *   const cmds = handlers.commands.listAll('claude');
+ */
+export * from './types.js';
+export { CommandsHandler, commandsHandler } from './commands.js';
+export { HooksHandler } from './hooks.js';
+export { SkillsHandler } from './skills.js';
+export { RulesHandler } from './rules.js';
+export { McpHandler, getMcpConfigPath } from './mcp.js';
+export { PermissionsHandler } from './permissions.js';
+export { SubagentsHandler, subagentsHandler } from './subagents.js';
+import { commandsHandler } from './commands.js';
+import { HooksHandler } from './hooks.js';
+import { SkillsHandler } from './skills.js';
+import { RulesHandler } from './rules.js';
+import { McpHandler } from './mcp.js';
+import { PermissionsHandler } from './permissions.js';
+import { subagentsHandler } from './subagents.js';
+/** All resource handlers keyed by kind. */
+export const handlers = {
+    command: commandsHandler,
+    commands: commandsHandler,
+    hook: HooksHandler,
+    hooks: HooksHandler,
+    skill: SkillsHandler,
+    skills: SkillsHandler,
+    rule: RulesHandler,
+    rules: RulesHandler,
+    mcp: McpHandler,
+    permission: PermissionsHandler,
+    permissions: PermissionsHandler,
+    subagent: subagentsHandler,
+    subagents: subagentsHandler,
+};
+/** Get a handler by resource kind. */
+export function getHandler(kind) {
+    switch (kind) {
+        case 'command':
+            return commandsHandler;
+        case 'hook':
+            return HooksHandler;
+        case 'skill':
+            return SkillsHandler;
+        case 'rule':
+            return RulesHandler;
+        case 'mcp':
+            return McpHandler;
+        case 'permission':
+            return PermissionsHandler;
+        case 'subagent':
+            return subagentsHandler;
+        default:
+            return null;
+    }
+}
+/** All resource kinds. */
+export const RESOURCE_KINDS = [
+    'command',
+    'hook',
+    'skill',
+    'rule',
+    'mcp',
+    'permission',
+    'subagent',
+];

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

@@ -0,0 +1,34 @@
+/**
+ * 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;