@skillkit/agents 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -200,10 +200,608 @@ declare class UniversalAdapter implements AgentAdapter {
     isDetected(): Promise<boolean>;
 }
 
+/**
+ * Agent Features Types
+ *
+ * Type definitions for enhanced agent-specific features.
+ */
+
+/**
+ * Permission level for agent actions
+ */
+type PermissionLevel = 'allow' | 'deny' | 'ask';
+/**
+ * Permission pattern for file/resource access
+ */
+interface PermissionPattern {
+    /** Pattern to match (glob or regex) */
+    pattern: string;
+    /** Permission level */
+    level: PermissionLevel;
+    /** Description of why this permission is needed */
+    reason?: string;
+}
+/**
+ * Permission configuration for skills
+ */
+interface PermissionConfig {
+    /** File access permissions */
+    files?: PermissionPattern[];
+    /** Command execution permissions */
+    commands?: PermissionPattern[];
+    /** Network access permissions */
+    network?: PermissionPattern[];
+    /** Environment variable access */
+    env?: PermissionPattern[];
+    /** Default permission level */
+    default?: PermissionLevel;
+}
+/**
+ * Glob pattern configuration for file-scoped skills
+ */
+interface GlobConfig {
+    /** Patterns to include */
+    include: string[];
+    /** Patterns to exclude */
+    exclude?: string[];
+    /** Whether to match directories */
+    matchDirectories?: boolean;
+    /** Whether to match hidden files */
+    matchHidden?: boolean;
+}
+/**
+ * Bootstrap file types
+ */
+type BootstrapFileType = 'agents' | 'soul' | 'tools' | 'identity' | 'context' | 'brief' | 'history';
+/**
+ * Bootstrap file configuration
+ */
+interface BootstrapFile {
+    /** File type */
+    type: BootstrapFileType;
+    /** File name */
+    name: string;
+    /** File content */
+    content: string;
+    /** Priority (higher = loaded first) */
+    priority?: number;
+    /** Whether file is required */
+    required?: boolean;
+}
+/**
+ * Agent mode types
+ */
+type AgentMode = 'code' | 'architect' | 'ask' | 'debug' | 'review' | 'test' | 'docs';
+/**
+ * Mode configuration
+ */
+interface ModeConfig {
+    /** Mode name */
+    mode: AgentMode;
+    /** Mode description */
+    description: string;
+    /** Skills available in this mode */
+    skills: string[];
+    /** Tools available in this mode */
+    tools?: string[];
+    /** Default prompt prefix for this mode */
+    promptPrefix?: string;
+    /** Allowed file patterns in this mode */
+    allowedFiles?: string[];
+}
+/**
+ * Tool whitelist configuration
+ */
+interface ToolWhitelistConfig {
+    /** Allowed tools */
+    allowed: string[];
+    /** Denied tools */
+    denied?: string[];
+    /** Mode for handling unlisted tools */
+    unlisted?: 'allow' | 'deny' | 'ask';
+}
+/**
+ * Skill package configuration (for .skill bundles)
+ */
+interface SkillPackageConfig {
+    /** Package name */
+    name: string;
+    /** Package version */
+    version: string;
+    /** Package description */
+    description?: string;
+    /** Entry point skill */
+    entryPoint: string;
+    /** Included skill files */
+    files: string[];
+    /** Dependencies */
+    dependencies?: string[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent feature capabilities
+ */
+interface AgentCapabilities {
+    /** Supports permission system */
+    permissions: boolean;
+    /** Supports glob patterns */
+    globs: boolean;
+    /** Supports bootstrap files */
+    bootstrapFiles: boolean;
+    /** Supports multi-mode */
+    multiMode: boolean;
+    /** Supports tool whitelisting */
+    toolWhitelist: boolean;
+    /** Supports .skill packages */
+    skillPackages: boolean;
+    /** Supports hooks */
+    hooks: boolean;
+    /** Supports subagents */
+    subagents: boolean;
+}
+/**
+ * Agent feature set
+ */
+interface AgentFeatures {
+    /** Agent type */
+    agent: AgentType;
+    /** Agent capabilities */
+    capabilities: AgentCapabilities;
+    /** Permission configuration */
+    permissions?: PermissionConfig;
+    /** Glob configuration */
+    globs?: GlobConfig;
+    /** Bootstrap files */
+    bootstrapFiles?: BootstrapFile[];
+    /** Mode configurations */
+    modes?: ModeConfig[];
+    /** Tool whitelist */
+    toolWhitelist?: ToolWhitelistConfig;
+}
+/**
+ * Feature generation options
+ */
+interface FeatureGenerationOptions {
+    /** Target agent */
+    agent: AgentType;
+    /** Output directory */
+    outputDir?: string;
+    /** Include optional files */
+    includeOptional?: boolean;
+    /** Dry run (don't write files) */
+    dryRun?: boolean;
+}
+/**
+ * Feature validation result
+ */
+interface FeatureValidationResult {
+    /** Whether features are valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: string[];
+    /** Validation warnings */
+    warnings: string[];
+    /** Agent capabilities used */
+    usedCapabilities: (keyof AgentCapabilities)[];
+}
+
+/**
+ * Permissions System
+ *
+ * Implements permission patterns for agent skill access control.
+ */
+
+/**
+ * PermissionManager - Manage skill permissions
+ */
+declare class PermissionManager {
+    private config;
+    constructor(config?: PermissionConfig);
+    /**
+     * Set permission configuration
+     */
+    setConfig(config: PermissionConfig): void;
+    /**
+     * Get permission configuration
+     */
+    getConfig(): PermissionConfig;
+    /**
+     * Check file access permission
+     */
+    checkFileAccess(path: string): PermissionLevel;
+    /**
+     * Check command execution permission
+     */
+    checkCommandAccess(command: string): PermissionLevel;
+    /**
+     * Check network access permission
+     */
+    checkNetworkAccess(url: string): PermissionLevel;
+    /**
+     * Check environment variable access
+     */
+    checkEnvAccess(varName: string): PermissionLevel;
+    /**
+     * Add file permission pattern
+     */
+    addFilePattern(pattern: PermissionPattern): void;
+    /**
+     * Add command permission pattern
+     */
+    addCommandPattern(pattern: PermissionPattern): void;
+    /**
+     * Check pattern against permission list
+     */
+    private checkPattern;
+    /**
+     * Match value against pattern (glob-style)
+     *
+     * Uses minimatch for safe glob matching, avoiding ReDoS vulnerabilities.
+     */
+    private matchPattern;
+    /**
+     * Generate OpenCode-compatible permission config
+     */
+    generateOpenCodeConfig(): string;
+    /**
+     * Generate SKILL.md metadata for permissions
+     */
+    generateSkillMetadata(): Record<string, unknown>;
+    /**
+     * Parse permissions from SKILL.md metadata
+     */
+    static fromMetadata(metadata: Record<string, unknown>): PermissionConfig;
+    /**
+     * Merge two permission configs
+     */
+    static merge(base: PermissionConfig, override: PermissionConfig): PermissionConfig;
+}
+/**
+ * Create a PermissionManager instance
+ */
+declare function createPermissionManager(config?: PermissionConfig): PermissionManager;
+/**
+ * Quick permission check helpers
+ */
+declare function isAllowed(level: PermissionLevel): boolean;
+declare function isDenied(level: PermissionLevel): boolean;
+declare function needsConfirmation(level: PermissionLevel): boolean;
+
+/**
+ * Glob Pattern System
+ *
+ * Implements file pattern matching for file-scoped skills.
+ */
+
+/**
+ * GlobMatcher - Match files against glob patterns
+ */
+declare class GlobMatcher {
+    private config;
+    private includePatterns;
+    private excludePatterns;
+    constructor(config: GlobConfig);
+    /**
+     * Check if a file matches the glob patterns
+     */
+    matches(filePath: string): boolean;
+    /**
+     * Filter a list of files
+     */
+    filter(filePaths: string[]): string[];
+    /**
+     * Get all include patterns
+     */
+    getIncludePatterns(): string[];
+    /**
+     * Get all exclude patterns
+     */
+    getExcludePatterns(): string[];
+    /**
+     * Add an include pattern
+     */
+    addInclude(pattern: string): void;
+    /**
+     * Add an exclude pattern
+     */
+    addExclude(pattern: string): void;
+    /**
+     * Convert glob pattern to regex using minimatch
+     *
+     * Uses the battle-tested minimatch library to avoid ReDoS vulnerabilities
+     * and ensure consistent glob matching behavior.
+     */
+    private patternToRegex;
+    /**
+     * Check if file is hidden (starts with .)
+     */
+    private isHiddenFile;
+    /**
+     * Generate Cursor-compatible globs field
+     */
+    generateCursorGlobs(): string[];
+    /**
+     * Generate MDC frontmatter
+     */
+    generateMDCFrontmatter(): string;
+}
+/**
+ * Create a GlobMatcher instance
+ */
+declare function createGlobMatcher(config: GlobConfig): GlobMatcher;
+/**
+ * Create a GlobMatcher from a single pattern
+ */
+declare function matchPattern(pattern: string): GlobMatcher;
+/**
+ * Parse glob patterns from Cursor MDC format
+ */
+declare function parseGlobsFromMDC(content: string): GlobConfig | null;
+/**
+ * Common glob patterns for different file types
+ */
+declare const COMMON_PATTERNS: {
+    /** All TypeScript files */
+    readonly typescript: readonly ["**/*.ts", "**/*.tsx"];
+    /** All JavaScript files */
+    readonly javascript: readonly ["**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
+    /** All test files */
+    readonly tests: readonly ["**/*.test.*", "**/*.spec.*", "**/__tests__/**"];
+    /** All config files */
+    readonly configs: readonly ["*.config.*", "*rc", "*rc.*", "*.json", "*.yaml", "*.yml"];
+    /** All source files */
+    readonly source: readonly ["src/**/*"];
+    /** All documentation */
+    readonly docs: readonly ["**/*.md", "docs/**/*", "README*"];
+    /** Node modules (usually excluded) */
+    readonly nodeModules: readonly ["**/node_modules/**"];
+    /** Build outputs (usually excluded) */
+    readonly buildOutputs: readonly ["**/dist/**", "**/build/**", "**/.next/**"];
+    /** All files */
+    readonly all: readonly ["**/*"];
+};
+/**
+ * Create glob config from common pattern names
+ */
+declare function fromCommonPatterns(includeNames: (keyof typeof COMMON_PATTERNS)[], excludeNames?: (keyof typeof COMMON_PATTERNS)[]): GlobConfig;
+
+/**
+ * Bootstrap Files System
+ *
+ * Implements bootstrap file generation for agents that support them.
+ */
+
+/**
+ * BootstrapManager - Manage bootstrap files for agents
+ */
+declare class BootstrapManager {
+    private files;
+    /**
+     * Add a bootstrap file
+     */
+    addFile(file: BootstrapFile): void;
+    /**
+     * Get a bootstrap file by type
+     */
+    getFile(type: BootstrapFileType): BootstrapFile | undefined;
+    /**
+     * Get all bootstrap files
+     */
+    getAllFiles(): BootstrapFile[];
+    /**
+     * Get files sorted by priority
+     */
+    getFilesByPriority(): BootstrapFile[];
+    /**
+     * Remove a bootstrap file
+     */
+    removeFile(type: BootstrapFileType): boolean;
+    /**
+     * Check if a file type exists
+     */
+    hasFile(type: BootstrapFileType): boolean;
+    /**
+     * Create AGENTS.md file
+     */
+    createAgentsFile(agents: AgentDefinition[]): void;
+    /**
+     * Create SOUL.md file
+     */
+    createSoulFile(soul: SoulDefinition): void;
+    /**
+     * Create TOOLS.md file
+     */
+    createToolsFile(tools: ToolDefinition[]): void;
+    /**
+     * Create IDENTITY.md file
+     */
+    createIdentityFile(identity: IdentityDefinition): void;
+    /**
+     * Create CONTEXT.md file
+     */
+    createContextFile(context: ContextDefinition): void;
+    /**
+     * Generate all files as a map
+     */
+    generateFiles(): Map<string, string>;
+    /**
+     * Generate combined content for agents without file support
+     */
+    generateCombinedContent(): string;
+    /**
+     * Get default file name for a type
+     */
+    static getDefaultFileName(type: BootstrapFileType): string;
+}
+/**
+ * Agent definition for AGENTS.md
+ */
+interface AgentDefinition {
+    name: string;
+    description?: string;
+    capabilities?: string[];
+    constraints?: string[];
+}
+/**
+ * Soul definition for SOUL.md
+ */
+interface SoulDefinition {
+    personality?: string;
+    values?: string[];
+    communication?: string;
+    rules?: string[];
+}
+/**
+ * Tool definition for TOOLS.md
+ */
+interface ToolDefinition {
+    name: string;
+    description?: string;
+    usage?: string;
+    examples?: string[];
+}
+/**
+ * Identity definition for IDENTITY.md
+ */
+interface IdentityDefinition {
+    name?: string;
+    role?: string;
+    description?: string;
+    expertise?: string[];
+}
+/**
+ * Context definition for CONTEXT.md
+ */
+interface ContextDefinition {
+    project?: string;
+    techStack?: string[];
+    conventions?: string[];
+    currentTask?: string;
+}
+/**
+ * Create a BootstrapManager instance
+ */
+declare function createBootstrapManager(): BootstrapManager;
+/**
+ * Create a complete bootstrap set from definitions
+ */
+declare function createBootstrapSet(options: {
+    agents?: AgentDefinition[];
+    soul?: SoulDefinition;
+    tools?: ToolDefinition[];
+    identity?: IdentityDefinition;
+    context?: ContextDefinition;
+}): BootstrapManager;
+
+/**
+ * Multi-Mode System
+ *
+ * Implements multi-mode support for agents that support different operating modes.
+ */
+
+/**
+ * ModeManager - Manage agent operating modes
+ */
+declare class ModeManager {
+    private modes;
+    private currentMode;
+    private modeListeners;
+    constructor(modes?: ModeConfig[]);
+    /**
+     * Add a mode configuration
+     */
+    addMode(config: ModeConfig): void;
+    /**
+     * Get a mode configuration
+     */
+    getMode(mode: AgentMode): ModeConfig | undefined;
+    /**
+     * Get all mode configurations
+     */
+    getAllModes(): ModeConfig[];
+    /**
+     * Get available mode names
+     */
+    getAvailableModes(): AgentMode[];
+    /**
+     * Set the current mode
+     */
+    setMode(mode: AgentMode): void;
+    /**
+     * Get the current mode
+     */
+    getCurrentMode(): AgentMode;
+    /**
+     * Get current mode configuration
+     */
+    getCurrentModeConfig(): ModeConfig | undefined;
+    /**
+     * Get skills for current mode
+     */
+    getCurrentSkills(): string[];
+    /**
+     * Get tools for current mode
+     */
+    getCurrentTools(): string[];
+    /**
+     * Check if a skill is available in current mode
+     */
+    isSkillAvailable(skillName: string): boolean;
+    /**
+     * Check if a file is allowed in current mode
+     */
+    isFileAllowed(filePath: string): boolean;
+    /**
+     * Add mode change listener
+     */
+    addModeListener(listener: ModeChangeListener): void;
+    /**
+     * Remove mode change listener
+     */
+    removeModeListener(listener: ModeChangeListener): void;
+    /**
+     * Create a mode from default configuration
+     */
+    addDefaultMode(mode: AgentMode, skills: string[]): void;
+    /**
+     * Generate mode-specific prompt prefix
+     */
+    getPromptPrefix(): string;
+    /**
+     * Generate Roo-compatible mode configuration
+     */
+    generateRooConfig(): Record<string, unknown>;
+    /**
+     * Generate mode documentation
+     */
+    generateModeDocumentation(): string;
+}
+/**
+ * Mode change listener type
+ */
+type ModeChangeListener = (newMode: AgentMode, previousMode: AgentMode, config: ModeConfig) => void;
+/**
+ * Create a ModeManager instance
+ */
+declare function createModeManager(modes?: ModeConfig[]): ModeManager;
+/**
+ * Create a ModeManager with all default modes
+ */
+declare function createDefaultModeManager(skillsPerMode: Partial<Record<AgentMode, string[]>>): ModeManager;
+/**
+ * Get default configuration for a mode
+ */
+declare function getDefaultModeConfig(mode: AgentMode): Omit<ModeConfig, 'skills'>;
+/**
+ * All available agent modes
+ */
+declare const ALL_MODES: AgentMode[];
+
 declare function getAdapter(type: AgentType): AgentAdapter;
 declare function getAllAdapters(): AgentAdapter[];
 declare function detectAgent(): Promise<AgentType>;
 declare function getSkillsDir(type: AgentType): string;
 declare function getConfigFile(type: AgentType): string;
 
-export { type AgentAdapter, AmpAdapter, AntigravityAdapter, ClaudeCodeAdapter, ClawdbotAdapter, CodexAdapter, CursorAdapter, DroidAdapter, GeminiCliAdapter, GitHubCopilotAdapter, GooseAdapter, KiloAdapter, KiroCliAdapter, OpenCodeAdapter, RooAdapter, TraeAdapter, UniversalAdapter, WindsurfAdapter, createSkillXml, detectAgent, escapeXml, getAdapter, getAllAdapters, getConfigFile, getSkillsDir };
+export { ALL_MODES, type AgentAdapter, type AgentCapabilities, type AgentDefinition, type AgentFeatures, type AgentMode, AmpAdapter, AntigravityAdapter, type BootstrapFile, type BootstrapFileType, BootstrapManager, COMMON_PATTERNS, ClaudeCodeAdapter, ClawdbotAdapter, CodexAdapter, type ContextDefinition, CursorAdapter, DroidAdapter, type FeatureGenerationOptions, type FeatureValidationResult, GeminiCliAdapter, GitHubCopilotAdapter, type GlobConfig, GlobMatcher, GooseAdapter, type IdentityDefinition, KiloAdapter, KiroCliAdapter, type ModeChangeListener, type ModeConfig, ModeManager, OpenCodeAdapter, type PermissionConfig, type PermissionLevel, PermissionManager, type PermissionPattern, RooAdapter, type SkillPackageConfig, type SoulDefinition, type ToolDefinition, type ToolWhitelistConfig, TraeAdapter, UniversalAdapter, WindsurfAdapter, createBootstrapManager, createBootstrapSet, createDefaultModeManager, createGlobMatcher, createModeManager, createPermissionManager, createSkillXml, detectAgent, escapeXml, fromCommonPatterns, getAdapter, getAllAdapters, getConfigFile, getDefaultModeConfig, getSkillsDir, isAllowed, isDenied, matchPattern, needsConfirmation, parseGlobsFromMDC };