skill-tree 0.1.5 → 0.1.6

package/dist/index.d.mts

@@ -34,7 +34,7 @@ interface Skill {
     metrics: SkillMetrics;
     /** Upstream tracking for skills imported with 'link' mode */
     upstream?: SkillUpstream;
-    source?: SkillSource;
+    source?: SkillSource$1;
     /** Taxonomy classification (from skill indexer) */
     taxonomy?: SkillTaxonomy;
     /** External source information (for imported skills) */
@@ -90,7 +90,7 @@ interface SkillMetrics {
     /** Average confidence from matching */
     averageConfidence?: number;
 }
-interface SkillSource {
+interface SkillSource$1 {
     /** Where the skill came from */
     type: 'extracted' | 'manual' | 'imported' | 'composed';
     /** Original source location (git URL, local path, etc.) */
@@ -1212,6 +1212,17 @@ interface LoadoutCompilerConfig {
     /** Minimum similarity threshold for semantic matching (default: 0.6) */
     semanticThreshold?: number;
 }
+/**
+ * Configuration for CatalogRenderer (browsable skill catalog)
+ */
+interface CatalogRendererConfig {
+    /** Max categories to show at each level (default: 12) */
+    maxCategoriesPerLevel: number;
+    /** Max skills to list at leaf nodes (default: 8) */
+    maxSkillsAtLeaf: number;
+    /** Max summary length for leaf-level skill descriptions (default: 80) */
+    maxSummaryLength: number;
+}
 /**
  * Eviction strategy when maxExpanded is reached
  */
@@ -1248,6 +1259,10 @@ interface GraphServerConfig {
     outputFormat?: 'xml' | 'markdown';
     /** Include token estimates in output (default: false) */
     includeTokenEstimates?: boolean;
+    /** Enable catalog browsing for large libraries (default: true) */
+    enableCatalog?: boolean;
+    /** Catalog renderer config overrides */
+    catalogConfig?: Partial<CatalogRendererConfig>;
 }
 /**
  * Events emitted by the serving layer
@@ -1270,6 +1285,12 @@ type ServingEvent = {
 } | {
     type: 'pending:denied';
     skillIds: string[];
+} | {
+    type: 'catalog:browsed';
+    path: string[];
+} | {
+    type: 'catalog:added';
+    skillId: string;
 };
 /**
  * Handler for serving events
@@ -1300,6 +1321,7 @@ declare class SkillGraphServer {
     private compiler;
     private projectDetector;
     private viewRenderer;
+    private catalogRenderer;
     private state;
     private handlers;
     private lruOrder;
@@ -1408,9 +1430,25 @@ declare class SkillGraphServer {
      */
     agentListLoadout(): LoadoutView;
     /**
-     * Render current state as system prompt content
+     * Agent browses the skill catalog at a given path.
+     * Returns rendered category view (subcategories or skill summaries at leaf).
+     * Pass no path for the top-level overview.
      */
-    renderSystemPrompt(): string;
+    agentBrowseCatalog(path?: string[]): Promise<string>;
+    /**
+     * Agent adds a skill discovered via browsing directly to loadout and expands it.
+     * Bridges browse → loadout: found it in catalog, now load it.
+     */
+    agentAddFromCatalog(skillId: string): Promise<{
+        added: boolean;
+        pending: boolean;
+        expanded: boolean;
+    }>;
+    /**
+     * Render current state as system prompt content.
+     * Includes catalog overview when catalog is enabled.
+     */
+    renderSystemPrompt(): Promise<string>;
     /**
      * Estimate total tokens for current loadout
      */
@@ -3169,11 +3207,13 @@ declare class ViewRenderer {
      */
     toSummaries(state: LoadoutState): SkillSummary[];
     /**
-     * Get summary for a skill (short description)
+     * Get summary for a skill (short description).
+     * Delegates to shared getSkillSummary utility.
      */
     private getSummary;
     /**
-     * Escape special XML characters
+     * Escape special XML characters.
+     * Delegates to shared escapeXml utility.
      */
     private escapeXml;
     /**
@@ -3248,6 +3288,63 @@ declare class ProjectDetector {
     private detectDirectoryPatterns;
 }
 
+/**
+ * CatalogRenderer - Renders compressed, browsable skill catalog views
+ *
+ * Provides hierarchical discovery for large skill libraries by rendering
+ * taxonomy trees or tag-based groupings at minimal token cost. Agents can
+ * browse categories level by level instead of seeing a flat list.
+ *
+ * Two strategies:
+ * 1. Taxonomy-based: Uses taxonomy_nodes from SQLite (preferred)
+ * 2. Tag-based fallback: Groups skills by primary tag when no taxonomy exists
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Renders compressed, browsable skill catalog views for agent consumption
+ */
+declare class CatalogRenderer {
+    private storage;
+    private config;
+    private overviewCache;
+    private static readonly CACHE_TTL_MS;
+    constructor(storage: StorageAdapter, config?: Partial<CatalogRendererConfig>);
+    /**
+     * Render level-0 catalog overview for system prompt injection.
+     * Shows top-level categories with counts. ~200 tokens.
+     * Returns empty string if no skills exist.
+     * Results are cached for 60 seconds to avoid repeated storage queries.
+     */
+    renderOverview(): Promise<string>;
+    /**
+     * Render a specific category path for browse drill-down.
+     * Shows subcategories at intermediate nodes, or skill summaries at leaf nodes.
+     */
+    renderCategory(path: string[]): Promise<string>;
+    /**
+     * Invalidate the overview cache (e.g., after skill changes).
+     */
+    invalidateCache(): void;
+    /**
+     * Render the overview XML shell with a list of categories.
+     * Used by both taxonomy-based and tag-based paths.
+     */
+    private renderOverviewXml;
+    private renderOverviewFromNodes;
+    private renderCategoryFromTaxonomy;
+    private renderOverviewFromTags;
+    private renderCategoryFromTags;
+    private renderLeafSkills;
+    private groupByPrimaryTag;
+    /**
+     * Pre-compute counts for a list of nodes, avoiding redundant recursive walks.
+     */
+    private withCounts;
+    private countNodeSkills;
+}
+
 /**
  * Built-in Loadout Profiles
  *
@@ -3566,6 +3663,218 @@ declare function createDefaultSyncConfig(remoteUrl: string, agentId: string, opt
     environment?: string;
 }): SyncConfig;
 
+/**
+ * Indexer Service - Wraps the skill indexer functionality for use with SkillBank
+ *
+ * This service provides a bridge between the skill indexer (scraper/) and the
+ * main skill-tree SkillBank. It can work in two modes:
+ *
+ * 1. Standalone mode: Direct database operations (default)
+ * 2. Integrated mode: Uses SkillBank as the storage backend
+ */
+
+/**
+ * Skill source for scraping
+ */
+interface SkillSource {
+    type: "awesome-list" | "repository";
+    url: string;
+}
+/**
+ * Indexer configuration (service-level)
+ */
+interface IndexerServiceConfig {
+    /** GitHub API token */
+    githubToken?: string;
+    /** Anthropic API key for classification */
+    anthropicApiKey?: string;
+    /** Claude model to use */
+    claudeModel?: string;
+    /** Database path for standalone mode */
+    databasePath?: string;
+    /** Batch size for processing */
+    batchSize?: number;
+    /** Concurrency limit */
+    concurrency?: number;
+    /** Minimum confidence for classification */
+    minConfidence?: number;
+    /** Cache directory */
+    cacheDir?: string;
+    /** Cache TTL in seconds */
+    cacheTtlSeconds?: number;
+    /** Pre-loaded scraper module. When provided, skips filesystem-based module discovery entirely. */
+    scraperModules?: any;
+}
+/**
+ * Scrape result
+ */
+interface ScrapeResult {
+    discovered: number;
+    scraped: number;
+    skipped: number;
+    failed: number;
+    unchanged: number;
+    errors: string[];
+}
+/**
+ * Index result
+ */
+interface IndexResult {
+    indexed: number;
+    skipped: number;
+    failed: number;
+    errors: string[];
+}
+/**
+ * Relationship detection result
+ */
+interface RelationshipResult {
+    detected: number;
+    skipped: number;
+    errors: string[];
+}
+/**
+ * Taxonomy node for tree display
+ */
+interface TaxonomyNode {
+    id: string;
+    name: string;
+    path: string[];
+    skillCount: number;
+    children: TaxonomyNode[];
+}
+/**
+ * Database statistics
+ */
+interface IndexerStats {
+    totalSkills: number;
+    indexedSkills: number;
+    rawSkills: number;
+    failedSkills: number;
+    taxonomyNodes: number;
+    relationships: number;
+    sources: number;
+}
+/**
+ * IndexerService - Manages skill discovery, classification, and relationship detection
+ */
+declare class IndexerService {
+    private serviceConfig;
+    private globalConfig;
+    private skillBank?;
+    private initialized;
+    private scraperModule?;
+    private indexerModule?;
+    private databaseModule?;
+    private db?;
+    constructor(config?: IndexerServiceConfig, skillBank?: SkillBank);
+    /**
+     * Get effective configuration
+     */
+    getConfig(): IndexerServiceConfig;
+    /**
+     * Initialize the service (lazy load scraper modules)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if the indexer is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if running in degraded mode (no scraper modules)
+     */
+    isDegradedMode(): boolean;
+    /**
+     * Scrape skills from GitHub sources
+     */
+    scrape(sources: SkillSource[], options?: {
+        force?: boolean;
+    }): Promise<ScrapeResult>;
+    /**
+     * Classify unindexed skills using AI
+     */
+    classify(options?: {
+        skillId?: string;
+        all?: boolean;
+    }): Promise<IndexResult>;
+    /**
+     * Detect relationships between skills
+     */
+    detectRelationships(options?: {
+        skillId?: string;
+        useAi?: boolean;
+    }): Promise<RelationshipResult>;
+    /**
+     * Detect relationships for a single skill
+     */
+    private detectSkillRelationships;
+    /**
+     * Get taxonomy tree
+     */
+    getTaxonomyTree(rootPath?: string[]): Promise<TaxonomyNode>;
+    /**
+     * Wrap tree nodes returned from SQLite storage into a root node
+     */
+    private wrapTreeNodes;
+    /**
+     * Convert storage tree node to TaxonomyNode format
+     */
+    private convertToTaxonomyNode;
+    /**
+     * Count total skills in a node tree
+     */
+    private countNodeSkills;
+    /**
+     * Build taxonomy tree from flat nodes
+     */
+    private buildTaxonomyTree;
+    /**
+     * Build taxonomy tree from skills
+     */
+    private buildTaxonomyTreeFromSkills;
+    /**
+     * Get indexer statistics
+     */
+    getStats(): Promise<IndexerStats>;
+    /**
+     * Count nodes in taxonomy tree
+     */
+    private countTaxonomyNodes;
+    /**
+     * Scrape and index skills directly into SkillBank
+     * This is the streamlined workflow for integrated mode
+     */
+    scrapeAndIndex(sources: SkillSource[], options?: {
+        force?: boolean;
+        autoClassify?: boolean;
+        detectRelationships?: boolean;
+    }): Promise<{
+        scraped: ScrapeResult;
+        indexed: IndexResult;
+        relationships: RelationshipResult;
+        skillsAdded: string[];
+    }>;
+    /**
+     * Import skills from indexer database into SkillBank
+     */
+    importFromIndexerDb(options?: {
+        status?: "raw" | "indexed" | "failed";
+        limit?: number;
+    }): Promise<{
+        imported: number;
+        failed: number;
+        skills: Skill[];
+    }>;
+    /**
+     * Get default skill sources from config
+     */
+    getDefaultSources(): SkillSource[];
+    /**
+     * Close database connections
+     */
+    close(): Promise<void>;
+}
+
 /**
  * skill-tree - A library for managing agent skill versions and evolution
  *
@@ -3579,4 +3888,4 @@ declare function createDefaultSyncConfig(remoteUrl: string, agentId: string, opt
  */
 declare const VERSION = "0.1.0";
 
-export { type AgentConfig, AgentsGenerator, type AgentsGeneratorConfig, AgentsParser, AgentsSync, type BaseHookContext, type BumpType, CachedStorageAdapter, type CachedStorageConfig, type ConflictConfig, type ConflictResolution$1 as ConflictResolution, ConflictStore, type ConflictStrategy, DEFAULT_AGENTS_CONFIG, type DiscoveredSkill, type EvictionStrategy, type ExpandTrigger, type ExpandTriggerConfig, type FederatedRemoteConfig, type FederationEvent, type FederationEventHandler, FederationManager, type FederationManagerOptions, type FetchResult, type ForkOptions, GitSyncAdapter, type GitSyncAdapterOptions, type SyncResult$1 as GitSyncResult, type GraphServerConfig, type HookContext, type HookEvent, type HookExecutionResult, type HookHandler, type HookPriority, HookRegistry, type HookResult, type ImportMode, type ImportOptions, type ImportResult, LineageTracker, type LineageTree, LoadoutCompiler, type LoadoutCompilerConfig, type LoadoutCriteria, type LoadoutSource, type LoadoutState, type LoadoutView, type MaterializationConfig, Materializer, MemoryStorageAdapter, type MergeConfig, type MergeConflict, type MergePreview, type MergeResult, type MergeStrategy, type MergeSuggestion, type MigrationOptions, type MigrationProgressItem, type MigrationResult, type NewVersionOptions, type ParsedAgentSkill, type ParsedAgentsFile, type ParsedVersion, type ProjectContext, ProjectDetector, type PullOptions, type PullUpstreamOptions, type PullUpstreamResult, type PushOptions, type RegisterHookOptions, type RegisteredHook, type RemoteConfig, RemoteManager, type RemoteState, RemoteStore, type RollbackOptions, type ServingEvent, type ServingEventHandler, type ShareOptions, type ShareResult, type Skill, type SkillAccessControl, SkillBank, type SkillBankConfig, type SkillBankStats, type SkillChange, type SkillConflict, type SkillCrudHookContext, type SkillDiffChanges, type SkillFilter, type SkillFork, type SkillFormat, SkillGraphServer, type SkillLineage, type SkillMergeResult, SkillMerger, type SkillMetrics, type SkillNamespace, type SkillScope, type SkillSelector, type SkillServingMetadata, type SkillSource, type SkillState, type SkillStatus, type SkillSummary, type SkillSyncState, type SkillTreeEvent, type SkillTreeEventHandler, type SkillUpstream, type SkillVersion, type SkillVisibility, type StorageAdapter, type StorageConfig, type StorageHookContext, type SyncBehaviorConfig, type SyncConfig, type ConflictResolution as SyncConflictResolution, type SyncError, SyncManager, type SyncManagerOptions, type SyncOptions, type SyncResult, type SyncState, type SyncStatus, type UpstreamUpdate, VERSION, type VersionChanges, type VersionDiff, ViewRenderer, type ViewRendererConfig, builtInProfiles, bumpVersion, codeReviewProfile, combineHandlers, compareVersions, conditionalHook, createAgentsGenerator, createAgentsParser, createAgentsSync, createBackupHook, createConflictStore, createDefaultSyncConfig, createFederationManager, createGitSyncAdapter, createLoggingHook, createSaveValidationHook, createSkillBank, createSkillMerger, createSyncManager, debuggingProfile, devopsProfile, discoverSkills, documentationProfile, formatVersion, generateAgentsMd, getBuiltInProfile, getLatestVersion, hasSkilltreeDir, hookRegistry, implementationProfile, importFromAgentsMd, inferBumpType, isValidVersion, listBuiltInProfiles, migrateStorage, parseVersion, refactoringProfile, satisfiesRange, securityProfile, sortVersions, testingProfile, writeAgentsMd };
+export { type AgentConfig, AgentsGenerator, type AgentsGeneratorConfig, AgentsParser, AgentsSync, type BaseHookContext, type BumpType, CachedStorageAdapter, type CachedStorageConfig, CatalogRenderer, type CatalogRendererConfig, type ConflictConfig, type ConflictResolution$1 as ConflictResolution, ConflictStore, type ConflictStrategy, DEFAULT_AGENTS_CONFIG, type DiscoveredSkill, type EvictionStrategy, type ExpandTrigger, type ExpandTriggerConfig, type FederatedRemoteConfig, type FederationEvent, type FederationEventHandler, FederationManager, type FederationManagerOptions, type FetchResult, type ForkOptions, GitSyncAdapter, type GitSyncAdapterOptions, type SyncResult$1 as GitSyncResult, type GraphServerConfig, type HookContext, type HookEvent, type HookExecutionResult, type HookHandler, type HookPriority, HookRegistry, type HookResult, type ImportMode, type ImportOptions, type ImportResult, type IndexResult, IndexerService, type IndexerServiceConfig, type SkillSource as IndexerSkillSource, type IndexerStats, LineageTracker, type LineageTree, LoadoutCompiler, type LoadoutCompilerConfig, type LoadoutCriteria, type LoadoutSource, type LoadoutState, type LoadoutView, type MaterializationConfig, Materializer, MemoryStorageAdapter, type MergeConfig, type MergeConflict, type MergePreview, type MergeResult, type MergeStrategy, type MergeSuggestion, type MigrationOptions, type MigrationProgressItem, type MigrationResult, type NewVersionOptions, type ParsedAgentSkill, type ParsedAgentsFile, type ParsedVersion, type ProjectContext, ProjectDetector, type PullOptions, type PullUpstreamOptions, type PullUpstreamResult, type PushOptions, type RegisterHookOptions, type RegisteredHook, type RelationshipResult, type RemoteConfig, RemoteManager, type RemoteState, RemoteStore, type RollbackOptions, type ScrapeResult, type ServingEvent, type ServingEventHandler, type ShareOptions, type ShareResult, type Skill, type SkillAccessControl, SkillBank, type SkillBankConfig, type SkillBankStats, type SkillChange, type SkillConflict, type SkillCrudHookContext, type SkillDiffChanges, type SkillFilter, type SkillFork, type SkillFormat, SkillGraphServer, type SkillLineage, type SkillMergeResult, SkillMerger, type SkillMetrics, type SkillNamespace, type SkillScope, type SkillSelector, type SkillServingMetadata, type SkillSource$1 as SkillSource, type SkillState, type SkillStatus, type SkillSummary, type SkillSyncState, type SkillTreeEvent, type SkillTreeEventHandler, type SkillUpstream, type SkillVersion, type SkillVisibility, type StorageAdapter, type StorageConfig, type StorageHookContext, type SyncBehaviorConfig, type SyncConfig, type ConflictResolution as SyncConflictResolution, type SyncError, SyncManager, type SyncManagerOptions, type SyncOptions, type SyncResult, type SyncState, type SyncStatus, type TaxonomyNode, type UpstreamUpdate, VERSION, type VersionChanges, type VersionDiff, ViewRenderer, type ViewRendererConfig, builtInProfiles, bumpVersion, codeReviewProfile, combineHandlers, compareVersions, conditionalHook, createAgentsGenerator, createAgentsParser, createAgentsSync, createBackupHook, createConflictStore, createDefaultSyncConfig, createFederationManager, createGitSyncAdapter, createLoggingHook, createSaveValidationHook, createSkillBank, createSkillMerger, createSyncManager, debuggingProfile, devopsProfile, discoverSkills, documentationProfile, formatVersion, generateAgentsMd, getBuiltInProfile, getLatestVersion, hasSkilltreeDir, hookRegistry, implementationProfile, importFromAgentsMd, inferBumpType, isValidVersion, listBuiltInProfiles, migrateStorage, parseVersion, refactoringProfile, satisfiesRange, securityProfile, sortVersions, testingProfile, writeAgentsMd };