@sstar/skill-install 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ekko.bao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,296 @@
+# Agent Skill Installer
+
+A command-line tool for installing Agent Skills from various sources (public URLs, Wiki with authentication, or local archive files). Automatically downloads, extracts, validates, and installs skills for **Claude Code** or **Codex**.
+
+## Features
+
+- **Multi-tool support**: Works with both Claude Code (`~/.claude/skills/`) and Codex (`~/.codex/skills/`)
+- **Auto-detect source**: Automatically detects if the source is a public URL, Wiki URL (with auth), or local file
+- **Multiple archive formats**: Supports `.zip` and `.tar.gz` archives
+- **Strict validation**: Validates that archives contain a valid `SKILL.md` with required frontmatter
+- **Wiki authentication**: Supports authentication with internal Confluence Wiki
+- **Skill management**: List installed skills and uninstall them
+- **Interactive prompts**: Choose between global/local directories and AI tools
+- **Self-signed certificates**: Built-in support for corporate SSL certificates
+
+## What are Skills?
+
+Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. At its core, a skill is a folder containing a `SKILL.md` file with metadata (`name` and `description`) and instructions.
+
+Learn more at: https://agentskills.io/what-are-skills
+
+## Installation
+
+```bash
+cd /home/ekko.bao/work/tools/wiki_download
+npm install
+npm run build
+npm link  # Optional: for global installation
+```
+
+## Usage
+
+```bash
+# Install with interactive AI tool and directory selection
+skill-install install https://github.com/user/repo/archive/main.zip
+
+# Install for specific AI tool (skip prompt)
+skill-install -t claude install https://github.com/user/repo/archive/main.zip
+skill-install -t codex install https://github.com/user/repo/archive/main.zip
+
+# Install to global directory explicitly
+skill-install install https://example.com/skill.zip --global
+
+# Install to local directory explicitly
+skill-install install https://example.com/skill.zip --local
+
+# Install with custom directory
+skill-install -s /path/to/skills install https://example.com/skill.zip
+
+# Install from Wiki with authentication
+skill-install install https://wiki.company.com/download/attachments/123/skill.zip -u username
+
+# Install from a local archive file
+skill-install install ./my-skill.zip
+
+# List installed skills (prompts for AI tool)
+skill-install list
+
+# List installed skills for specific AI tool (skip prompt)
+skill-install -t claude list
+skill-install -t codex list
+
+# List skills from both global and local directories
+skill-install list --all
+
+# Uninstall a skill (prompts for AI tool)
+skill-install uninstall my-skill
+
+# Uninstall from specific AI tool (skip prompt)
+skill-install -t claude uninstall my-skill
+skill-install -t codex uninstall my-skill
+
+# Force reinstall if skill already exists
+skill-install install ./my-skill.zip --force
+```
+
+## Options
+
+### Global Options
+| Option | Description |
+|--------|-------------|
+| `-t, --tool <tool>` | AI tool: `claude` or `codex` (skip prompt if specified) |
+| `-s, --skills-dir <path>` | Custom skills directory |
+| `-v, --verbose` | Enable verbose logging |
+| `-h, --help` | Display help |
+
+**Note**: If `-t` is not specified, the tool will prompt interactively to choose between Claude Code and Codex.
+
+### Install Command
+| Option | Description |
+|--------|-------------|
+| `<source>` | URL or local file path to skill archive |
+| `-g, --global` | Install to global directory (`~/.claude/skills/` or `~/.codex/skills/`) |
+| `-l, --local` | Install to local directory (`./.claude/skills/` or `./.codex/skills/`) |
+| `-u, --username <username>` | Wiki username (for Wiki URLs) |
+| `-p, --password <password>` | Wiki password (or use env var) |
+| `--allow-self-signed` | Allow self-signed SSL certificates (default: true) |
+| `-f, --force` | Reinstall if skill already exists |
+
+**Note**: If neither `-g` nor `-l` nor `-s` is specified, the tool will prompt interactively to choose between global and local directories.
+
+### List Command
+| Option | Description |
+|--------|-------------|
+| `-a, --all` | List skills from both global and local directories |
+
+### Uninstall Command
+| Option | Description |
+|--------|-------------|
+| `[name]` | Name of the skill to uninstall (optional - leave empty to select from list) |
+| `-y, --yes` | Skip confirmation prompt |
+
+**Note**: If no skill name is provided, the tool will display all installed skills and allow you to select which ones to uninstall by entering numbers separated by spaces (e.g., `1 3 5`).
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WIKI_USERNAME` | Default Wiki username |
+| `WIKI_PASSWORD` | Default Wiki password |
+
+## Skill Validation
+
+A valid skill must have a `SKILL.md` file at the root with YAML frontmatter containing:
+
+```yaml
+---
+name: my-skill
+description: A brief description of what this skill does
+---
+
+# My Skill
+
+Instructions for the agent...
+```
+
+The tool validates:
+- `SKILL.md` exists
+- YAML frontmatter is present (wrapped in `---`)
+- `name` field is present
+- `description` field is present
+
+## Skill Directory Structure
+
+Skills can be installed to different locations based on the AI tool:
+
+### Claude Code
+- **Global**: `~/.claude/skills/` - Available to all projects
+- **Local**: `./.claude/skills/` - Project-specific
+
+### Codex
+- **Global**: `~/.codex/skills/` - Available to all projects
+- **Local**: `./.codex/skills/` - Project-specific
+
+### Directory Selection
+- **Global**: Use `--global` flag or select "1" when prompted (recommended for commonly used skills)
+- **Local**: Use `--local` flag or select "2" when prompted (recommended for project-specific skills)
+- **Custom**: Use `-s /path/to/skills` for a custom location
+
+A typical installed skill:
+
+```
+~/.claude/skills/my-skill/
+├── SKILL.md          # Required: instructions + metadata
+├── scripts/          # Optional: executable code
+├── references/       # Optional: documentation
+└── assets/           # Optional: templates, resources
+```
+
+## Examples
+
+### Interactive installation (prompts for AI tool and directory)
+
+```bash
+skill-install install https://github.com/user/repo/archive/main.zip
+
+# Output:
+# Select AI tool:
+#   1. Claude Code (~/.claude/skills/)
+#   2. Codex      (~/.codex/skills/)
+#
+# Choose [1/2]: 1
+#
+# Select installation directory:
+#   1. Global: /home/user/.claude/skills
+#   2. Local:  /home/user/project/.claude/skills
+#
+# Choose [1/2]: 1
+```
+
+### Install for specific AI tool (skip prompt)
+
+```bash
+# Install for Claude Code
+skill-install -t claude install https://example.com/skill.zip
+
+# Install for Codex
+skill-install -t codex install https://example.com/skill.zip
+
+# Install to Codex global directory
+skill-install -t codex install https://example.com/skill.zip --global
+```
+
+### Install to specific directory
+
+```bash
+# Install to global directory
+skill-install install https://example.com/skill.zip --global
+
+# Install to local directory
+skill-install install https://example.com/skill.zip --local
+
+# Install to custom directory
+skill-install -s /custom/path install https://example.com/skill.zip
+```
+
+### Install from Wiki
+
+```bash
+skill-install install "https://wiki.company.com/download/attachments/12345/skill.zip?api=v2" -u john.doe
+```
+
+### Install from local file
+
+```bash
+skill-install install ~/Downloads/my-skill.tar.gz
+```
+
+### List and uninstall
+
+```bash
+# List skills (prompts for AI tool)
+skill-install list
+
+# List skills for specific AI tool (skip prompt)
+skill-install -t claude list
+skill-install -t codex list
+
+# List skills from both directories
+skill-install -t claude list --all
+
+# Uninstall a specific skill (prompts for AI tool)
+skill-install uninstall my-skill
+
+# Uninstall without prompts (specify AI tool and skip confirmation)
+skill-install -t codex uninstall my-skill -y
+
+# Interactive uninstall (select from list)
+skill-install uninstall
+
+# Output:
+# Select AI tool:
+#   1. Claude Code (~/.claude/skills/)
+#   2. Codex      (~/.codex/skills/)
+#
+# Choose [1/2]: 1
+#
+# Installed skills:
+#
+#   [1] repo-git
+#       Provides multi-repository version control capabilities.
+#
+#   [2] pdf-processing
+#       Extract text and tables from PDF files.
+#
+# Enter the numbers of the skills to uninstall (separated by spaces, e.g., "1 3 5"):
+# Press Enter to cancel:
+# Your choice: 1 2
+#
+# Selected skills: repo-git, pdf-processing
+```
+
+## Project Structure
+
+```
+src/
+├── cli.ts                    # CLI entry point
+├── installer/
+│   └── install-service.ts    # Core installation logic
+├── download/
+│   └── download-manager.ts   # Download manager (wiki + public)
+├── archive/
+│   └── archive-extractor.ts  # Archive extraction (ZIP, tar.gz)
+├── source/
+│   └── source-detector.ts    # Source type detection
+├── skills/
+│   ├── skills-manager.ts     # List/uninstall operations
+│   └── skill-validator.ts    # SKILL.md validation
+├── auth/                     # Wiki authentication
+├── http/                     # HTTP client with cookies
+└── core/                     # Error handling & logging
+```
+
+## License
+
+MIT

package/dist/archive/archive-extractor.d.ts

@@ -0,0 +1,29 @@
+export type ArchiveType = 'zip' | 'tar' | 'tar.gz' | 'tgz' | 'unknown';
+export declare class ArchiveExtractor {
+    private readonly logger;
+    /**
+     * Detect the archive type from a filename
+     */
+    detectArchiveType(filename: string): ArchiveType;
+    /**
+     * Extract an archive to a directory
+     * @param archivePath Path to the archive file
+     * @param targetDir Directory to extract to
+     * @throws WikiError if extraction fails
+     */
+    extract(archivePath: string, targetDir: string): Promise<void>;
+    /**
+     * Extract a ZIP archive
+     */
+    private extractZip;
+    /**
+     * Extract a tar/tar.gz archive
+     */
+    private extractTar;
+    /**
+     * Get the root directory name from an archive
+     * Useful for detecting if the archive contains a single root directory
+     */
+    getRootDirectoryName(archivePath: string): Promise<string | null>;
+    private getZipRootDir;
+}

package/dist/archive/archive-extractor.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchiveExtractor = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const tar_1 = require("tar");
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const logger_1 = require("../core/logger");
+const errors_1 = require("../core/errors");
+class ArchiveExtractor {
+    constructor() {
+        this.logger = new logger_1.Logger('ArchiveExtractor');
+    }
+    /**
+     * Detect the archive type from a filename
+     */
+    detectArchiveType(filename) {
+        const ext = (0, path_1.extname)(filename).toLowerCase();
+        const base = (0, path_1.basename)(filename, ext).toLowerCase();
+        // Check for compound extensions
+        if (filename.toLowerCase().endsWith('.tar.gz') || filename.toLowerCase().endsWith('.tgz')) {
+            return 'tar.gz';
+        }
+        if (ext === '.zip') {
+            return 'zip';
+        }
+        if (ext === '.tar' || base.endsWith('.tar')) {
+            return 'tar';
+        }
+        return 'unknown';
+    }
+    /**
+     * Extract an archive to a directory
+     * @param archivePath Path to the archive file
+     * @param targetDir Directory to extract to
+     * @throws WikiError if extraction fails
+     */
+    async extract(archivePath, targetDir) {
+        const archiveType = this.detectArchiveType(archivePath);
+        this.logger.info(`Extracting ${archiveType} archive: ${archivePath} -> ${targetDir}`);
+        switch (archiveType) {
+            case 'zip':
+                await this.extractZip(archivePath, targetDir);
+                break;
+            case 'tar':
+            case 'tar.gz':
+            case 'tgz':
+                await this.extractTar(archivePath, targetDir);
+                break;
+            default:
+                throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Unknown archive type: ${archivePath}. Supported formats: .zip, .tar, .tar.gz`);
+        }
+        this.logger.info(`Extraction complete: ${targetDir}`);
+    }
+    /**
+     * Extract a ZIP archive
+     */
+    async extractZip(archivePath, targetDir) {
+        try {
+            const zip = new adm_zip_1.default(archivePath);
+            zip.extractAllTo(targetDir, true);
+        }
+        catch (error) {
+            throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Failed to extract ZIP archive: ${archivePath}`, error);
+        }
+    }
+    /**
+     * Extract a tar/tar.gz archive
+     */
+    async extractTar(archivePath, targetDir) {
+        try {
+            await (0, promises_1.mkdir)(targetDir, { recursive: true });
+            await (0, tar_1.extract)({
+                file: archivePath,
+                cwd: targetDir,
+                strip: 1 // Strip the root directory if present
+            });
+        }
+        catch (error) {
+            throw new errors_1.WikiError(errors_1.ErrorType.EXTRACTION_FAILED, `Failed to extract tar archive: ${archivePath}`, error);
+        }
+    }
+    /**
+     * Get the root directory name from an archive
+     * Useful for detecting if the archive contains a single root directory
+     */
+    async getRootDirectoryName(archivePath) {
+        const archiveType = this.detectArchiveType(archivePath);
+        if (archiveType === 'zip') {
+            return this.getZipRootDir(archivePath);
+        }
+        if (archiveType === 'tar' || archiveType === 'tar.gz' || archiveType === 'tgz') {
+            // For tar archives, we'll just return null and let the extraction handle it
+            return null;
+        }
+        return null;
+    }
+    getZipRootDir(archivePath) {
+        try {
+            const zip = new adm_zip_1.default(archivePath);
+            const entries = zip.getEntries();
+            if (entries.length === 0) {
+                return null;
+            }
+            // Get the first entry's path
+            const firstEntry = entries[0].entryName;
+            // Check if all entries share a common root directory
+            const parts = firstEntry.split('/');
+            if (parts.length > 1) {
+                return parts[0];
+            }
+            return null;
+        }
+        catch (error) {
+            this.logger.warn(`Failed to determine root directory: ${error}`);
+            return null;
+        }
+    }
+}
+exports.ArchiveExtractor = ArchiveExtractor;

package/dist/auth/auth-service.d.ts

@@ -0,0 +1,21 @@
+import { HttpClient } from '../http/http-client';
+export interface AuthConfig {
+    baseUrl: string;
+    username: string;
+    password: string;
+}
+export declare class AuthService {
+    private readonly http;
+    private readonly config;
+    private readonly logger;
+    private session;
+    private authInFlight;
+    constructor(http: HttpClient, config: AuthConfig);
+    ensureAuthenticated(): Promise<void>;
+    private authenticate;
+    private getLoginFormData;
+    private performLogin;
+    private checkLoginSuccess;
+    private isSessionValid;
+    clearSession(): void;
+}