@sstar/skill-install 1.0.0

package/dist/installer/install-service.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstallService = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const os_1 = require("os");
+const logger_1 = require("../core/logger");
+const errors_1 = require("../core/errors");
+const source_detector_1 = require("../source/source-detector");
+const download_manager_1 = require("../download/download-manager");
+const archive_extractor_1 = require("../archive/archive-extractor");
+const skill_validator_1 = require("../skills/skill-validator");
+const skills_manager_1 = require("../skills/skills-manager");
+class InstallService {
+    constructor() {
+        this.logger = new logger_1.Logger('InstallService');
+        this.sourceDetector = new source_detector_1.SourceDetector();
+        this.downloadManager = new download_manager_1.DownloadManager();
+        this.extractor = new archive_extractor_1.ArchiveExtractor();
+        this.validator = new skill_validator_1.SkillValidator();
+        this.skillsManager = new skills_manager_1.SkillsManager();
+    }
+    /**
+     * Install a skill from a source (URL or local file)
+     */
+    async install(options) {
+        const tempDir = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), 'skill-install-'));
+        try {
+            this.logger.info(`Installing skill from: ${options.source}`);
+            // Detect source type
+            const sourceInfo = this.sourceDetector.detect(options.source);
+            if (sourceInfo.type === 'unknown') {
+                throw new errors_1.WikiError(errors_1.ErrorType.INVALID_INPUT, `Unknown source type: ${options.source}. Please provide a valid URL or file path.`);
+            }
+            // Get the archive file path
+            let archivePath;
+            if (sourceInfo.type === 'local-file') {
+                // Use local file directly
+                archivePath = options.source;
+            }
+            else {
+                // Download the file
+                const filename = this.downloadManager.extractFilenameFromUrl(options.source) || 'skill-archive.zip';
+                archivePath = (0, path_1.join)(tempDir, filename);
+                const downloadResult = await this.downloadManager.download({
+                    url: options.source,
+                    outputPath: archivePath,
+                    username: options.username,
+                    password: options.password,
+                    baseUrl: sourceInfo.baseUrl,
+                    allowSelfSigned: options.allowSelfSigned,
+                    requireAuth: sourceInfo.type === 'wiki-url'
+                });
+                if (!downloadResult.success) {
+                    throw new errors_1.WikiError(errors_1.ErrorType.NETWORK, `Failed to download: ${downloadResult.error || 'Unknown error'}`);
+                }
+            }
+            // Extract archive
+            const extractDir = (0, path_1.join)(tempDir, 'extracted');
+            await (0, promises_1.mkdir)(extractDir, { recursive: true });
+            try {
+                await this.extractor.extract(archivePath, extractDir);
+            }
+            catch (error) {
+                throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Failed to extract archive: ${error.message}`, error);
+            }
+            // Find the skill directory (may be the root or a subdirectory)
+            const skillDir = await this.findSkillDirectory(extractDir);
+            if (!skillDir) {
+                throw new errors_1.WikiError(errors_1.ErrorType.INVALID_SKILL, 'No valid skill found in archive. A valid skill must contain SKILL.md with name and description.');
+            }
+            // Validate the skill
+            const metadata = await this.validator.validateOrThrow(skillDir);
+            // Check if already installed
+            const targetSkillsDir = this.skillsManager.getEffectiveSkillsDir(options.skillsDir);
+            const targetPath = (0, path_1.join)(targetSkillsDir, metadata.name);
+            if (!options.force && await this.skillsManager.isInstalled(metadata.name, options.skillsDir)) {
+                throw new errors_1.WikiError(errors_1.ErrorType.ALREADY_INSTALLED, `Skill "${metadata.name}" is already installed. Use --force to reinstall.`);
+            }
+            // Install to final location
+            await (0, promises_1.mkdir)(targetSkillsDir, { recursive: true });
+            // If the skill already exists and force is true, remove it first
+            if (options.force) {
+                try {
+                    await (0, promises_1.rm)(targetPath, { recursive: true, force: true });
+                }
+                catch {
+                    // Ignore if directory doesn't exist
+                }
+            }
+            // Move the skill directory to the final location
+            await this.moveDirectory(skillDir, targetPath);
+            this.logger.info(`Skill installed successfully: ${metadata.name} -> ${targetPath}`);
+            return {
+                success: true,
+                skillName: metadata.name,
+                skillPath: targetPath
+            };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Installation failed: ${errorMsg}`);
+            return {
+                success: false,
+                error: errorMsg
+            };
+        }
+        finally {
+            // Clean up temp directory
+            try {
+                await (0, promises_1.rm)(tempDir, { recursive: true, force: true });
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+    /**
+     * Find the skill directory in the extracted files
+     * The archive may contain a single root directory or have SKILL.md at root
+     */
+    async findSkillDirectory(extractDir) {
+        // First, check if SKILL.md exists at the root
+        const entries = await (0, promises_1.readdir)(extractDir, { withFileTypes: true });
+        // Check for SKILL.md at root level
+        const hasSkillMdAtRoot = entries.some(e => e.name === 'SKILL.md');
+        if (hasSkillMdAtRoot) {
+            const isValid = await this.validator.validate(extractDir);
+            if (isValid.valid) {
+                return extractDir;
+            }
+        }
+        // Check subdirectories
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const subDirPath = (0, path_1.join)(extractDir, entry.name);
+            const isValid = await this.validator.validate(subDirPath);
+            if (isValid.valid) {
+                return subDirPath;
+            }
+        }
+        return null;
+    }
+    /**
+     * Move a directory from one location to another
+     * Handles cross-device moves by copying and then deleting
+     */
+    async moveDirectory(source, target) {
+        try {
+            // Try rename first (fastest, works on same device)
+            await (0, promises_1.rename)(source, target);
+        }
+        catch (error) {
+            // If rename fails, try copy + delete
+            if (error.code === 'EXDEV') {
+                await this.copyDirectory(source, target);
+                await (0, promises_1.rm)(source, { recursive: true, force: true });
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Recursively copy a directory
+     */
+    async copyDirectory(source, target) {
+        await (0, promises_1.mkdir)(target, { recursive: true });
+        const entries = await (0, promises_1.readdir)(source, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourcePath = (0, path_1.join)(source, entry.name);
+            const targetPath = (0, path_1.join)(target, entry.name);
+            if (entry.isDirectory()) {
+                await this.copyDirectory(sourcePath, targetPath);
+            }
+            else {
+                await (0, promises_1.copyFile)(sourcePath, targetPath);
+            }
+        }
+    }
+}
+exports.InstallService = InstallService;

package/dist/skills/skill-validator.d.ts

@@ -0,0 +1,33 @@
+export interface SkillMetadata {
+    name: string;
+    description: string;
+}
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    [key: string]: any;
+}
+export interface ValidationResult {
+    valid: boolean;
+    metadata?: SkillMetadata;
+    error?: string;
+}
+export declare class SkillValidator {
+    private readonly logger;
+    /**
+     * Validate that a directory contains a valid skill
+     * @param skillPath Path to the skill directory
+     * @returns Validation result with metadata if valid
+     */
+    validate(skillPath: string): Promise<ValidationResult>;
+    private readSkillMd;
+    private parseFrontmatter;
+    private validateFrontmatter;
+    /**
+     * Validate and throw WikiError if invalid
+     * @param skillPath Path to the skill directory
+     * @returns Skill metadata if valid
+     * @throws WikiError if validation fails
+     */
+    validateOrThrow(skillPath: string): Promise<SkillMetadata>;
+}

package/dist/skills/skill-validator.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillValidator = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const js_yaml_1 = require("js-yaml");
+const logger_1 = require("../core/logger");
+const errors_1 = require("../core/errors");
+class SkillValidator {
+    constructor() {
+        this.logger = new logger_1.Logger('SkillValidator');
+    }
+    /**
+     * Validate that a directory contains a valid skill
+     * @param skillPath Path to the skill directory
+     * @returns Validation result with metadata if valid
+     */
+    async validate(skillPath) {
+        try {
+            const skillMdPath = (0, path_1.join)(skillPath, 'SKILL.md');
+            // Check if SKILL.md exists
+            const content = await this.readSkillMd(skillMdPath);
+            if (!content) {
+                this.logger.error(`SKILL.md not found at ${skillMdPath}`);
+                return {
+                    valid: false,
+                    error: 'SKILL.md not found'
+                };
+            }
+            // Parse YAML frontmatter
+            const frontmatter = this.parseFrontmatter(content);
+            if (!frontmatter) {
+                this.logger.error('No YAML frontmatter found in SKILL.md');
+                return {
+                    valid: false,
+                    error: 'SKILL.md must contain YAML frontmatter (wrapped in ---)'
+                };
+            }
+            // Validate required fields
+            const metadata = this.validateFrontmatter(frontmatter);
+            if (!metadata) {
+                return {
+                    valid: false,
+                    error: 'SKILL.md frontmatter must contain "name" and "description" fields'
+                };
+            }
+            this.logger.info(`Valid skill found: ${metadata.name}`);
+            return {
+                valid: true,
+                metadata
+            };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            this.logger.error(`Validation error: ${errorMsg}`);
+            return {
+                valid: false,
+                error: errorMsg
+            };
+        }
+    }
+    async readSkillMd(path) {
+        try {
+            const content = await (0, promises_1.readFile)(path, 'utf-8');
+            return content;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    parseFrontmatter(content) {
+        // Check for YAML frontmatter wrapped in ---
+        const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---/;
+        const match = content.match(frontmatterRegex);
+        if (!match || !match[1]) {
+            return null;
+        }
+        try {
+            const parsed = (0, js_yaml_1.load)(match[1]);
+            return parsed;
+        }
+        catch (error) {
+            this.logger.error(`Failed to parse YAML frontmatter: ${error}`);
+            return null;
+        }
+    }
+    validateFrontmatter(frontmatter) {
+        if (!frontmatter.name || typeof frontmatter.name !== 'string') {
+            this.logger.error('Missing or invalid "name" field in frontmatter');
+            return null;
+        }
+        if (!frontmatter.description || typeof frontmatter.description !== 'string') {
+            this.logger.error('Missing or invalid "description" field in frontmatter');
+            return null;
+        }
+        // Sanitize name (remove special characters, spaces)
+        const sanitizedName = frontmatter.name
+            .toLowerCase()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '');
+        return {
+            name: sanitizedName,
+            description: frontmatter.description
+        };
+    }
+    /**
+     * Validate and throw WikiError if invalid
+     * @param skillPath Path to the skill directory
+     * @returns Skill metadata if valid
+     * @throws WikiError if validation fails
+     */
+    async validateOrThrow(skillPath) {
+        const result = await this.validate(skillPath);
+        if (!result.valid) {
+            throw new errors_1.WikiError(errors_1.ErrorType.INVALID_SKILL, result.error || 'Invalid skill', result.error ? new Error(result.error) : undefined);
+        }
+        return result.metadata;
+    }
+}
+exports.SkillValidator = SkillValidator;

package/dist/skills/skills-manager.d.ts

@@ -0,0 +1,54 @@
+export type AiTool = 'claude' | 'codex';
+export interface InstalledSkill {
+    name: string;
+    description: string;
+    path: string;
+    tool: AiTool;
+}
+export declare class SkillsManager {
+    private readonly logger;
+    private readonly validator;
+    /**
+     * Get the global skills directory for the specified AI tool
+     */
+    getGlobalSkillsDir(aiTool?: AiTool): string;
+    /**
+     * Get the local skills directory for the specified AI tool
+     */
+    getLocalSkillsDir(aiTool?: AiTool): string;
+    /**
+     * Get both global and local directories for an AI tool
+     */
+    getSkillsDirs(aiTool?: AiTool): {
+        global: string;
+        local: string;
+    };
+    /**
+     * Get the effective skills directory
+     * Returns the custom directory if provided, otherwise global directory
+     */
+    getEffectiveSkillsDir(customDir?: string, aiTool?: AiTool): string;
+    /**
+     * List all installed skills
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @returns Array of installed skill metadata
+     */
+    listInstalled(skillsDir?: string, aiTool?: AiTool): Promise<InstalledSkill[]>;
+    /**
+     * Uninstall a skill by name
+     * @param name Name of the skill to uninstall
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @throws WikiError if skill not found or deletion fails
+     */
+    uninstall(name: string, skillsDir?: string, aiTool?: AiTool): Promise<void>;
+    /**
+     * Check if a skill is already installed
+     * @param name Name of the skill to check
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @returns true if skill is installed, false otherwise
+     */
+    isInstalled(name: string, skillsDir?: string, aiTool?: AiTool): Promise<boolean>;
+}

package/dist/skills/skills-manager.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillsManager = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const os_1 = require("os");
+const logger_1 = require("../core/logger");
+const errors_1 = require("../core/errors");
+const skill_validator_1 = require("./skill-validator");
+class SkillsManager {
+    constructor() {
+        this.logger = new logger_1.Logger('SkillsManager');
+        this.validator = new skill_validator_1.SkillValidator();
+    }
+    /**
+     * Get the global skills directory for the specified AI tool
+     */
+    getGlobalSkillsDir(aiTool = 'claude') {
+        return (0, path_1.join)((0, os_1.homedir)(), `.${aiTool}`, 'skills');
+    }
+    /**
+     * Get the local skills directory for the specified AI tool
+     */
+    getLocalSkillsDir(aiTool = 'claude') {
+        return (0, path_1.join)(process.cwd(), `.${aiTool}`, 'skills');
+    }
+    /**
+     * Get both global and local directories for an AI tool
+     */
+    getSkillsDirs(aiTool = 'claude') {
+        return {
+            global: this.getGlobalSkillsDir(aiTool),
+            local: this.getLocalSkillsDir(aiTool)
+        };
+    }
+    /**
+     * Get the effective skills directory
+     * Returns the custom directory if provided, otherwise global directory
+     */
+    getEffectiveSkillsDir(customDir, aiTool = 'claude') {
+        if (customDir) {
+            return customDir;
+        }
+        // Prefer global directory
+        return this.getGlobalSkillsDir(aiTool);
+    }
+    /**
+     * List all installed skills
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @returns Array of installed skill metadata
+     */
+    async listInstalled(skillsDir, aiTool = 'claude') {
+        const dir = this.getEffectiveSkillsDir(skillsDir, aiTool);
+        const skills = [];
+        this.logger.info(`Listing skills in: ${dir}`);
+        try {
+            const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const skillPath = (0, path_1.join)(dir, entry.name);
+                try {
+                    const metadata = await this.validator.validateOrThrow(skillPath);
+                    skills.push({
+                        name: metadata.name,
+                        description: metadata.description,
+                        path: skillPath,
+                        tool: aiTool
+                    });
+                }
+                catch (error) {
+                    // Skip invalid entries but log a warning
+                    this.logger.warn(`Skipping invalid skill directory: ${entry.name}`);
+                }
+            }
+            return skills;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Directory doesn't exist yet, return empty array
+                this.logger.info('Skills directory does not exist yet');
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Uninstall a skill by name
+     * @param name Name of the skill to uninstall
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @throws WikiError if skill not found or deletion fails
+     */
+    async uninstall(name, skillsDir, aiTool = 'claude') {
+        const dir = this.getEffectiveSkillsDir(skillsDir, aiTool);
+        const skillPath = (0, path_1.join)(dir, name);
+        this.logger.info(`Uninstalling skill: ${name} from ${skillPath}`);
+        // Check if skill exists
+        const skills = await this.listInstalled(dir, aiTool);
+        const skill = skills.find(s => s.name === name);
+        if (!skill) {
+            throw new errors_1.WikiError(errors_1.ErrorType.NOT_FOUND, `Skill "${name}" not found in ${dir}`);
+        }
+        // Delete the skill directory
+        try {
+            await (0, promises_1.rm)(skill.path, { recursive: true, force: true });
+            this.logger.info(`Successfully uninstalled skill: ${name}`);
+        }
+        catch (error) {
+            throw new errors_1.WikiError(errors_1.ErrorType.UNKNOWN, `Failed to delete skill directory: ${skill.path}`, error);
+        }
+    }
+    /**
+     * Check if a skill is already installed
+     * @param name Name of the skill to check
+     * @param skillsDir Path to skills directory (uses default if not provided)
+     * @param aiTool AI tool to use (default: 'claude')
+     * @returns true if skill is installed, false otherwise
+     */
+    async isInstalled(name, skillsDir, aiTool = 'claude') {
+        const skills = await this.listInstalled(skillsDir, aiTool);
+        return skills.some(s => s.name === name);
+    }
+}
+exports.SkillsManager = SkillsManager;

package/dist/source/source-detector.d.ts

@@ -0,0 +1,29 @@
+export type SourceType = 'local-file' | 'wiki-url' | 'public-url' | 'unknown';
+export interface SourceInfo {
+    type: SourceType;
+    path?: string;
+    url?: string;
+    baseUrl?: string;
+}
+export declare class SourceDetector {
+    private readonly logger;
+    /**
+     * Detect the type of source from a string
+     * @param source URL or file path
+     * @returns SourceInfo with detected type and relevant information
+     */
+    detect(source: string): SourceInfo;
+    /**
+     * Check if the source is a local file path
+     */
+    private isLocalFile;
+    /**
+     * Check if the URL is a Confluence Wiki download URL
+     * Typical pattern: /download/attachments/{pageId}/{filename}
+     */
+    private isWikiUrl;
+    /**
+     * Check if a source requires authentication
+     */
+    requiresAuthentication(source: string): boolean;
+}

package/dist/source/source-detector.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceDetector = void 0;
+const fs_1 = require("fs");
+const url_1 = require("url");
+const logger_1 = require("../core/logger");
+class SourceDetector {
+    constructor() {
+        this.logger = new logger_1.Logger('SourceDetector');
+    }
+    /**
+     * Detect the type of source from a string
+     * @param source URL or file path
+     * @returns SourceInfo with detected type and relevant information
+     */
+    detect(source) {
+        this.logger.debug(`Detecting source type for: ${source}`);
+        // Check if it's a local file
+        if (this.isLocalFile(source)) {
+            this.logger.info('Detected source type: local file');
+            return {
+                type: 'local-file',
+                path: source
+            };
+        }
+        // Try to parse as URL
+        try {
+            const url = new url_1.URL(source);
+            // Check if it's a wiki URL (Confluence-style download URL)
+            if (this.isWikiUrl(source)) {
+                this.logger.info('Detected source type: wiki URL');
+                return {
+                    type: 'wiki-url',
+                    url: source,
+                    baseUrl: `${url.protocol}//${url.host}`
+                };
+            }
+            // Otherwise, treat as public URL
+            this.logger.info('Detected source type: public URL');
+            return {
+                type: 'public-url',
+                url: source
+            };
+        }
+        catch {
+            // Not a valid URL or file path
+            this.logger.warn('Unknown source type');
+            return {
+                type: 'unknown'
+            };
+        }
+    }
+    /**
+     * Check if the source is a local file path
+     */
+    isLocalFile(source) {
+        // Check if file exists
+        if ((0, fs_1.existsSync)(source)) {
+            return true;
+        }
+        // Check if it looks like a file path (contains path separators, no protocol)
+        if (!source.includes('://') && (source.includes('/') || source.includes('\\'))) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if the URL is a Confluence Wiki download URL
+     * Typical pattern: /download/attachments/{pageId}/{filename}
+     */
+    isWikiUrl(url) {
+        const wikiPatterns = [
+            '/download/attachments/',
+            '/download/thumbnails/',
+            '/wiki/download/',
+            '/confluence/download/'
+        ];
+        return wikiPatterns.some(pattern => url.includes(pattern));
+    }
+    /**
+     * Check if a source requires authentication
+     */
+    requiresAuthentication(source) {
+        const info = this.detect(source);
+        return info.type === 'wiki-url';
+    }
+}
+exports.SourceDetector = SourceDetector;