@sstar/skill-install 1.0.0 → 1.1.0

package/dist/plugins/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Plugin and Marketplace type definitions for Claude Code
+ */
+/**
+ * Supported package types
+ */
+export declare enum PackageType {
+    SKILL = "skill",
+    PLUGIN = "plugin",
+    MARKETPLACE = "marketplace",
+    UNKNOWN = "unknown"
+}
+/**
+ * Plugin metadata from plugin.json
+ */
+export interface PluginMetadata {
+    name: string;
+    version?: string;
+    description?: string;
+    author?: AuthorInfo;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    commands?: string | string[];
+    agents?: string | string[];
+    hooks?: string | object;
+    mcpServers?: string | object;
+    lspServers?: string | object;
+    claudeCode?: {
+        minVersion?: string;
+    };
+}
+/**
+ * Author information
+ */
+export interface AuthorInfo {
+    name: string;
+    email?: string;
+    url?: string;
+}
+/**
+ * Marketplace metadata from marketplace.json
+ */
+export interface MarketplaceMetadata {
+    name: string;
+    description?: string;
+    version?: string;
+    owner: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    plugins: PluginDefinition[];
+    metadata?: {
+        description?: string;
+        version?: string;
+        pluginRoot?: string;
+    };
+}
+/**
+ * Plugin definition in marketplace.json
+ */
+export interface PluginDefinition {
+    name: string;
+    source: string | PluginSource;
+    description?: string;
+    version?: string;
+    author?: AuthorInfo;
+    homepage?: string;
+    repository?: string;
+    license?: string;
+    keywords?: string[];
+    category?: string;
+    tags?: string[];
+    commands?: string | string[];
+    agents?: string | string[];
+    hooks?: string | object;
+    mcpServers?: string | object;
+    lspServers?: string | object;
+    strict?: boolean;
+}
+/**
+ * Plugin source reference (matches official Claude Code schema)
+ */
+export interface PluginSource {
+    source: 'url' | 'github' | 'git' | 'npm' | 'file' | 'directory';
+    repo?: string;
+    url?: string;
+    path?: string;
+    ref?: string;
+    sha?: string;
+}
+/**
+ * Detected plugin information
+ */
+export interface PluginInfo {
+    name: string;
+    path: string;
+    version?: string;
+    source: 'plugin.json' | 'marketplace' | 'scanned' | 'standalone';
+    metadata: PluginMetadata | PluginDefinition;
+}
+/**
+ * Detected skill information
+ */
+export interface SkillInfo {
+    name: string;
+    path: string;
+    description: string;
+}
+/**
+ * Package structure after detection
+ */
+export interface PackageStructure {
+    type: PackageType;
+    plugins: PluginInfo[];
+    skills: SkillInfo[];
+    marketplace?: MarketplaceMetadata | null;
+    marketplaceAsPlugin?: PluginMetadata | null;
+    hasMarketplace: boolean;
+    hasPluginAtRoot: boolean;
+    hasPluginInClaudeDir: boolean;
+}
+/**
+ * Installation result types
+ */
+export interface BaseInstallResult {
+    type: 'marketplace' | 'plugin' | 'skill';
+    success: boolean;
+    path: string;
+}
+export interface MarketplaceInstallResult extends BaseInstallResult {
+    type: 'marketplace';
+    marketplace: string;
+    installedPlugins?: string[];
+    pluginAsPluginInstalled?: boolean;
+}
+export interface PluginInstallResult extends BaseInstallResult {
+    type: 'plugin';
+    plugin: string;
+    version?: string;
+    marketplace?: string;
+    error?: string;
+}
+export interface SkillInstallResult extends BaseInstallResult {
+    type: 'skill';
+    skill: string;
+    description?: string;
+}
+export type InstallResult = MarketplaceInstallResult | PluginInstallResult | SkillInstallResult;
+/**
+ * Marketplace info in known_marketplaces.json
+ */
+export interface KnownMarketplace {
+    source: PluginSource;
+    installLocation: string;
+    lastUpdated: string;
+}
+/**
+ * Installed plugin info in installed_plugins.json
+ */
+export interface InstalledPluginEntry {
+    name: string;
+    scope: 'user' | 'local';
+    installPath: string;
+    version: string;
+    installedAt: string;
+    lastUpdated?: string;
+    isLocal: boolean;
+    projectPath?: string;
+}
+/**
+ * known_marketplaces.json structure
+ */
+export interface KnownMarketplacesJson {
+    [marketplaceName: string]: KnownMarketplace;
+}
+/**
+ * installed_plugins.json structure
+ */
+export interface InstalledPluginsJson {
+    version: 2;
+    plugins: {
+        [pluginKey: string]: InstalledPluginEntry[];
+    };
+}
+/**
+ * Plugin list for user selection
+ */
+export interface SelectablePlugin {
+    name: string;
+    version?: string;
+    description?: string;
+    path: string;
+    fromMarketplace?: string;
+}

package/dist/plugins/types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Plugin and Marketplace type definitions for Claude Code
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageType = void 0;
+/**
+ * Supported package types
+ */
+var PackageType;
+(function (PackageType) {
+    PackageType["SKILL"] = "skill";
+    PackageType["PLUGIN"] = "plugin";
+    PackageType["MARKETPLACE"] = "marketplace";
+    PackageType["UNKNOWN"] = "unknown";
+})(PackageType || (exports.PackageType = PackageType = {}));

package/dist/wiki/index.d.ts

@@ -0,0 +1,3 @@
+export { WikiSearcher, WikiSkillItem, SearchOptions } from './wiki-searcher';
+export { WikiParser, ParsedSkillItem } from './wiki-parser';
+export { SkillSelector } from './skill-selector';

package/dist/wiki/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillSelector = exports.WikiParser = exports.WikiSearcher = void 0;
+var wiki_searcher_1 = require("./wiki-searcher");
+Object.defineProperty(exports, "WikiSearcher", { enumerable: true, get: function () { return wiki_searcher_1.WikiSearcher; } });
+var wiki_parser_1 = require("./wiki-parser");
+Object.defineProperty(exports, "WikiParser", { enumerable: true, get: function () { return wiki_parser_1.WikiParser; } });
+var skill_selector_1 = require("./skill-selector");
+Object.defineProperty(exports, "SkillSelector", { enumerable: true, get: function () { return skill_selector_1.SkillSelector; } });

package/dist/wiki/skill-selector.d.ts

@@ -0,0 +1,13 @@
+import { ParsedSkillItem } from './wiki-parser';
+export declare class SkillSelector {
+    private readonly logger;
+    /**
+     * Display skill list and wait for user selection
+     * Returns the download URL of selected skill, or null if cancelled
+     */
+    displayAndSelect(items: ParsedSkillItem[]): Promise<string | null>;
+    /**
+     * Prompt user to select a skill from the list
+     */
+    private promptChoice;
+}

package/dist/wiki/skill-selector.js

@@ -0,0 +1,104 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillSelector = void 0;
+const readline_1 = __importDefault(require("readline"));
+const logger_1 = require("../core/logger");
+// Color codes for terminal output
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m'
+};
+class SkillSelector {
+    constructor() {
+        this.logger = new logger_1.Logger('SkillSelector');
+    }
+    /**
+     * Display skill list and wait for user selection
+     * Returns the download URL of selected skill, or null if cancelled
+     */
+    async displayAndSelect(items) {
+        if (items.length === 0) {
+            this.logger.info('No skills found to display.');
+            return null;
+        }
+        console.log('');
+        console.log(`${colors.cyan}Found ${items.length} skill(s):${colors.reset}`);
+        console.log('');
+        // Display all skills
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            // Add separator line before each skill
+            console.log(`${colors.dim}${'─'.repeat(60)}${colors.reset}`);
+            // Index with color
+            console.log(`${colors.bright}${colors.green}[${i + 1}]${colors.reset} ${colors.bright}${colors.yellow}${item.name}${colors.reset} ${colors.dim}${colors.gray}${item.pageUrl}${colors.reset}`);
+            // Display comment (may be multiline)
+            if (item.description) {
+                const lines = item.description.split('\n');
+                for (const line of lines) {
+                    console.log(`${colors.dim}    ${line}${colors.reset}`);
+                }
+            }
+        }
+        // Add separator line after the last skill
+        console.log(`${colors.dim}${'─'.repeat(60)}${colors.reset}`);
+        console.log('');
+        // Prompt for selection
+        const choice = await this.promptChoice(items.length);
+        if (choice === null) {
+            return null;
+        }
+        const selected = items[choice];
+        this.logger.info(`Selected: ${selected.name}`);
+        return selected.downloadUrl;
+    }
+    /**
+     * Prompt user to select a skill from the list
+     */
+    promptChoice(max) {
+        return new Promise((resolve) => {
+            const rl = readline_1.default.createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+            rl.question(`Select skill to install [1-${max}] (0 to cancel): `, (answer) => {
+                rl.close();
+                const trimmed = answer.trim();
+                if (trimmed === '') {
+                    console.log('No selection made.');
+                    resolve(null);
+                    return;
+                }
+                const num = parseInt(trimmed, 10);
+                if (isNaN(num)) {
+                    console.log('Invalid input. Please enter a number.');
+                    resolve(null);
+                    return;
+                }
+                if (num < 0 || num > max) {
+                    console.log(`Invalid selection. Please enter a number between 0 and ${max}.`);
+                    resolve(null);
+                    return;
+                }
+                if (num === 0) {
+                    console.log('Cancelled.');
+                    resolve(null);
+                    return;
+                }
+                resolve(num - 1); // Convert to 0-based index
+            });
+        });
+    }
+}
+exports.SkillSelector = SkillSelector;

package/dist/wiki/wiki-parser.d.ts

@@ -0,0 +1,26 @@
+import { HttpClient } from '../http/http-client';
+import { WikiSkillItem } from './wiki-searcher';
+export interface ParsedSkillItem extends WikiSkillItem {
+    description: string;
+}
+export declare class WikiParser {
+    private httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient);
+    /**
+     * Get attachment comment/description from the attachment metadata
+     */
+    getAttachmentComments(attachmentId: string): Promise<string>;
+    /**
+     * Get actual replies/comments on the attachment
+     */
+    private getAttachmentReplies;
+    /**
+     * Parse all skill items and fetch their comments
+     */
+    parseSkillItems(items: WikiSkillItem[]): Promise<ParsedSkillItem[]>;
+    /**
+     * Extract plain text description from HTML comments
+     */
+    private extractDescription;
+}

package/dist/wiki/wiki-parser.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WikiParser = void 0;
+const logger_1 = require("../core/logger");
+class WikiParser {
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+        this.logger = new logger_1.Logger('WikiParser');
+    }
+    /**
+     * Get attachment comment/description from the attachment metadata
+     */
+    async getAttachmentComments(attachmentId) {
+        try {
+            this.logger.info(`Fetching attachment details for ID: ${attachmentId}`);
+            // Get attachment details with metadata and extensions
+            const response = await this.httpClient.get(`/rest/api/content/${attachmentId}?expand=metadata,extensions`);
+            this.logger.debug(`Attachment API response status: ${response.status}`);
+            // Try to get comment from metadata or extensions
+            const comment = response.data?.metadata?.comment ||
+                response.data?.extensions?.comment ||
+                '';
+            if (comment) {
+                this.logger.info(`Found comment for attachment ${attachmentId}: ${comment}`);
+                return comment;
+            }
+            this.logger.debug(`No comment found in attachment metadata for: ${attachmentId}`);
+            // Fallback: try to get actual comments on the attachment
+            return await this.getAttachmentReplies(attachmentId);
+        }
+        catch (error) {
+            this.logger.error(`Failed to fetch attachment details for ${attachmentId}: ${error.message}`);
+            return '';
+        }
+    }
+    /**
+     * Get actual replies/comments on the attachment
+     */
+    async getAttachmentReplies(attachmentId) {
+        try {
+            const expandParams = 'body.view,body.export_view,body.storage';
+            const response = await this.httpClient.get(`/rest/api/content/${attachmentId}/child/comment?expand=${expandParams}`);
+            if (!response.data?.results?.length) {
+                return '';
+            }
+            const comments = response.data.results
+                .map((c) => {
+                return c.body?.view?.value ||
+                    c.body?.export_view?.value ||
+                    c.body?.storage?.value ||
+                    '';
+            })
+                .filter(Boolean)
+                .join('\n---\n');
+            this.logger.info(`Found ${response.data.results.length} comment(s) for attachment: ${attachmentId}`);
+            return comments;
+        }
+        catch (error) {
+            this.logger.debug(`Failed to fetch attachment replies: ${error.message}`);
+            return '';
+        }
+    }
+    /**
+     * Parse all skill items and fetch their comments
+     */
+    async parseSkillItems(items) {
+        const results = [];
+        this.logger.info(`Parsing ${items.length} skill item(s)...`);
+        for (const item of items) {
+            const comments = await this.getAttachmentComments(item.id);
+            results.push({
+                ...item,
+                description: this.extractDescription(comments)
+            });
+        }
+        return results;
+    }
+    /**
+     * Extract plain text description from HTML comments
+     */
+    extractDescription(htmlComments) {
+        if (!htmlComments || htmlComments.trim() === '') {
+            return 'No description available.';
+        }
+        // Decode HTML entities
+        let text = htmlComments
+            .replace(/ /g, ' ')
+            .replace(/&/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .replace(/&apos;/g, "'");
+        // Remove HTML tags
+        text = text.replace(/<[^>]*>/g, '');
+        // Clean up whitespace
+        text = text.replace(/\s+/g, ' ').trim();
+        // Limit to 200 characters
+        if (text.length > 200) {
+            text = text.substring(0, 197) + '...';
+        }
+        return text || 'No description available.';
+    }
+}
+exports.WikiParser = WikiParser;

package/dist/wiki/wiki-searcher.d.ts

@@ -0,0 +1,33 @@
+import { HttpClient } from '../http/http-client';
+export interface WikiSkillItem {
+    id: string;
+    name: string;
+    downloadUrl: string;
+    containerId: string;
+    pageUrl: string;
+}
+export interface SearchOptions {
+    username: string;
+    password: string;
+    baseUrl?: string;
+    allowSelfSigned?: boolean;
+}
+export declare class WikiSearcher {
+    private readonly logger;
+    private httpClient;
+    private authService;
+    get httpClientInstance(): HttpClient;
+    constructor();
+    /**
+     * Search for attachments with agent_skill tag
+     */
+    search(options: SearchOptions): Promise<WikiSkillItem[]>;
+    /**
+     * Filter search results by file extension
+     */
+    private filterByExtension;
+    /**
+     * Build full download URL from API response
+     */
+    private buildDownloadUrl;
+}

package/dist/wiki/wiki-searcher.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WikiSearcher = void 0;
+const http_client_1 = require("../http/http-client");
+const auth_service_1 = require("../auth/auth-service");
+const logger_1 = require("../core/logger");
+const errors_1 = require("../core/errors");
+const ALLOWED_EXTENSIONS = ['.tar.gz', '.tgz', '.zip'];
+class WikiSearcher {
+    get httpClientInstance() {
+        return this.httpClient;
+    }
+    constructor() {
+        this.logger = new logger_1.Logger('WikiSearcher');
+        // Will be initialized in search method
+        this.httpClient = null;
+        this.authService = null;
+    }
+    /**
+     * Search for attachments with agent_skill tag
+     */
+    async search(options) {
+        // Determine base URL from environment or use default
+        const baseUrl = options.baseUrl || process.env.WIKI_BASE_URL || '';
+        if (!baseUrl) {
+            throw new errors_1.WikiError(errors_1.ErrorType.INVALID_INPUT, 'Wiki base URL is required. Set WIKI_BASE_URL environment variable or use --wiki-url option.');
+        }
+        // Initialize HTTP client and auth service
+        this.httpClient = new http_client_1.HttpClient({
+            baseUrl,
+            allowSelfSigned: options.allowSelfSigned ?? true
+        });
+        this.authService = new auth_service_1.AuthService(this.httpClient, {
+            baseUrl,
+            username: options.username,
+            password: options.password
+        });
+        // Authenticate
+        this.logger.info('Authenticating to Wiki...');
+        await this.authService.ensureAuthenticated();
+        this.logger.info('Authentication successful');
+        // Search for attachments with agent_skill label
+        this.logger.info('Searching for attachments with agent_skill tag...');
+        const response = await this.httpClient.get('/rest/api/content/search?cql=type=attachment+and+label=agent_skill&expand=container,version');
+        if (!response.data?.results) {
+            this.logger.warn('No results found');
+            return [];
+        }
+        // Filter by allowed extensions
+        const filtered = this.filterByExtension(response.data.results, ALLOWED_EXTENSIONS);
+        this.logger.info(`Found ${filtered.length} skill(s) matching criteria`);
+        return filtered;
+    }
+    /**
+     * Filter search results by file extension
+     */
+    filterByExtension(results, extensions) {
+        const filtered = [];
+        if (!results) {
+            return filtered;
+        }
+        for (const item of results) {
+            const filename = item.title || '';
+            // Check if filename ends with any allowed extension
+            const hasAllowedExtension = extensions.some(ext => filename.endsWith(ext));
+            if (hasAllowedExtension) {
+                const baseUrl = this.httpClient.getBaseURL();
+                filtered.push({
+                    id: item.id,
+                    name: filename,
+                    downloadUrl: this.buildDownloadUrl(baseUrl, item),
+                    containerId: item.container?.id || '',
+                    pageUrl: item._links?.webui ? `${baseUrl}${item._links.webui}` : ''
+                });
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Build full download URL from API response
+     */
+    buildDownloadUrl(baseUrl, item) {
+        // Try to use download link from API
+        if (item._links?.download) {
+            const downloadPath = item._links.download;
+            if (downloadPath.startsWith('http')) {
+                return downloadPath;
+            }
+            return `${baseUrl}${downloadPath}`;
+        }
+        // Fallback: construct URL from attachment info
+        if (item.container?.id && item.id) {
+            return `${baseUrl}/download/attachments/${item.container.id}/${encodeURIComponent(item.title)}`;
+        }
+        throw new errors_1.WikiError(errors_1.ErrorType.INVALID_INPUT, `Cannot build download URL for attachment: ${item.title}`);
+    }
+}
+exports.WikiSearcher = WikiSearcher;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sstar/skill-install",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent Skill installation tool - download, extract, validate, and install skills for Claude Code and Codex",
   "main": "dist/index.js",
   "bin": {