@phuetz/code-buddy 0.1.13 → 0.1.14

package/dist/skills/hub.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Skills Hub
+ *
+ * OpenClaw ClawHub-inspired Skills Hub for searching, installing,
+ * publishing, and syncing skills from a remote registry.
+ *
+ * Provides lockfile-based integrity management, SHA-256 checksums,
+ * semver version comparison, and event-driven lifecycle hooks.
+ */
+import { EventEmitter } from 'events';
+export interface HubSkill {
+    /** Unique skill name */
+    name: string;
+    /** Semver version */
+    version: string;
+    /** Human-readable description */
+    description: string;
+    /** Author name */
+    author: string;
+    /** Tags for categorization and search */
+    tags: string[];
+    /** Total downloads */
+    downloads: number;
+    /** Star count */
+    stars: number;
+    /** Last updated timestamp (ISO 8601) */
+    updatedAt: string;
+    /** SHA-256 checksum of skill content */
+    checksum: string;
+    /** Size in bytes */
+    size: number;
+    /** Source repository URL */
+    repository?: string;
+}
+export interface HubSearchResult {
+    /** Matching skills */
+    skills: HubSkill[];
+    /** Total number of matches (may exceed returned skills) */
+    total: number;
+    /** Current page (1-indexed) */
+    page: number;
+    /** Page size */
+    pageSize: number;
+}
+export interface InstalledSkill {
+    /** Skill name */
+    name: string;
+    /** Installed version */
+    version: string;
+    /** Installation timestamp (epoch ms) */
+    installedAt: number;
+    /** Installation source */
+    source: 'hub' | 'local' | 'git';
+    /** SHA-256 checksum at install time */
+    checksum: string;
+    /** Path to installed SKILL.md */
+    path: string;
+}
+export interface HubConfig {
+    /** Remote registry API base URL */
+    registryUrl: string;
+    /** Local cache directory for downloaded skills */
+    cacheDir: string;
+    /** Directory where managed skills are installed */
+    skillsDir: string;
+    /** Path to the lockfile tracking installed skills */
+    lockfilePath: string;
+    /** Whether to auto-update on sync */
+    autoUpdate: boolean;
+    /** Interval in ms between update checks */
+    checkIntervalMs: number;
+}
+export interface HubSearchOptions {
+    /** Filter by tags */
+    tags?: string[];
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Results per page */
+    pageSize?: number;
+    /** Max results (alias for pageSize) */
+    limit?: number;
+    /** Sort by field */
+    sortBy?: 'name' | 'downloads' | 'stars' | 'updatedAt';
+    /** Sort order */
+    sortOrder?: 'asc' | 'desc';
+}
+interface Lockfile {
+    version: number;
+    updatedAt: string;
+    skills: Record<string, InstalledSkill>;
+}
+/**
+ * Compute SHA-256 checksum of content.
+ */
+export declare function computeChecksum(content: string): string;
+/**
+ * Parse a semver string into [major, minor, patch] components.
+ * Returns [0, 0, 0] for invalid input.
+ */
+export declare function parseSemver(version: string): [number, number, number];
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if a == b, 1 if a > b.
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+export declare class SkillsHub extends EventEmitter {
+    private config;
+    private lockfile;
+    private cache;
+    private cacheTimestamp;
+    private readonly cacheTtlMs;
+    constructor(config?: Partial<HubConfig>);
+    /**
+     * Ensure required directories exist.
+     */
+    private ensureDirectories;
+    /**
+     * Read the lockfile from disk. Returns an empty lockfile if not found.
+     */
+    private readLockfile;
+    /**
+     * Write the lockfile to disk.
+     */
+    private writeLockfile;
+    /**
+     * Get the lockfile contents (for testing / external inspection).
+     */
+    getLockfile(): Lockfile;
+    /**
+     * Search for skills by query string matching name, tags, and description.
+     * Checks local cache first, then fetches from remote registry.
+     */
+    search(query: string, options?: HubSearchOptions): Promise<HubSearchResult>;
+    /**
+     * Fetch skills from the remote registry.
+     * In a real implementation this would call the API.
+     * For now, returns cached data or an empty array.
+     */
+    private fetchRemoteSkills;
+    /**
+     * Read locally cached skills from the cache directory.
+     */
+    private getLocalCacheSkills;
+    /**
+     * Write skills to local cache file.
+     */
+    private writeLocalCache;
+    /**
+     * Install a skill by name and optional version.
+     * Downloads the skill content and writes it to the managed skills directory.
+     */
+    install(skillName: string, version?: string): Promise<InstalledSkill>;
+    /**
+     * Fetch skill content from the hub or local source.
+     * In a real implementation, this would download from the registry.
+     */
+    private fetchSkillContent;
+    /**
+     * Install a skill from local content string (for local/offline installs).
+     */
+    installFromContent(skillName: string, content: string, source?: InstalledSkill['source']): Promise<InstalledSkill>;
+    /**
+     * Remove an installed skill.
+     */
+    uninstall(skillName: string): Promise<boolean>;
+    /**
+     * Update one or all installed skills.
+     * If skillName is provided, updates that skill only.
+     * Otherwise updates all installed skills.
+     */
+    update(skillName?: string): Promise<InstalledSkill[]>;
+    /**
+     * Get skill info from the hub API.
+     */
+    private getHubSkillInfo;
+    /**
+     * Validate and prepare a skill for publishing.
+     * Reads the SKILL.md, validates YAML frontmatter, computes checksum,
+     * and returns the prepared HubSkill metadata.
+     */
+    publish(skillPath: string): Promise<HubSkill>;
+    /**
+     * Sync the lockfile with actually installed skills.
+     * - Removes lockfile entries for skills that no longer exist on disk.
+     * - Detects checksum mismatches (manual edits).
+     * - Optionally triggers updates if autoUpdate is enabled.
+     */
+    sync(): Promise<{
+        removed: string[];
+        mismatched: string[];
+        updated: string[];
+    }>;
+    /**
+     * List all installed skills from the lockfile.
+     */
+    list(): InstalledSkill[];
+    /**
+     * Get detailed information about an installed skill.
+     * Returns the lockfile entry plus the current on-disk content metadata.
+     */
+    info(skillName: string): {
+        installed: InstalledSkill;
+        content?: string;
+        integrityOk: boolean;
+    } | null;
+    /**
+     * Extract the version field from SKILL.md YAML frontmatter.
+     */
+    private extractVersionFromContent;
+    /**
+     * Validate skill content by parsing it and checking required fields.
+     */
+    private validateSkillContent;
+    /**
+     * Get hub configuration.
+     */
+    getConfig(): Readonly<HubConfig>;
+    /**
+     * Shutdown and cleanup.
+     */
+    shutdown(): void;
+}
+/**
+ * Get the singleton SkillsHub instance.
+ */
+export declare function getSkillsHub(config?: Partial<HubConfig>): SkillsHub;
+/**
+ * Reset the singleton SkillsHub instance (for testing).
+ */
+export declare function resetSkillsHub(): void;
+export default SkillsHub;