skillfish 1.0.0

package/dist/lib/installer.js

@@ -0,0 +1,163 @@
+/**
+ * Skill installation logic.
+ * Handles downloading, validating, and installing skills to agent directories.
+ */
+import { existsSync, mkdirSync, cpSync, rmSync, lstatSync, readdirSync, } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import degit from 'degit';
+import { SKILL_FILENAME } from './github.js';
+// === Error Types ===
+/**
+ * Thrown when SKILL.md is not found in downloaded content.
+ */
+export class SkillMdNotFoundError extends Error {
+    skillPath;
+    constructor(skillPath) {
+        super(`${SKILL_FILENAME} not found in downloaded content. Path may be incorrect.`);
+        this.skillPath = skillPath;
+        this.name = 'SkillMdNotFoundError';
+    }
+}
+// === Functions ===
+/**
+ * Recursively copies a directory while skipping symlinks for security.
+ * This prevents symlink attacks where malicious repos could link to sensitive files.
+ *
+ * SECURITY: Uses double-check pattern to minimize TOCTOU race window.
+ * The second lstatSync check immediately before cpSync reduces (but doesn't
+ * eliminate) the window for a race condition attack.
+ *
+ * @returns CopyResult with any warnings generated during copy
+ */
+export function safeCopyDir(src, dest) {
+    const warnings = [];
+    function copyRecursive(srcPath, destPath) {
+        mkdirSync(destPath, { recursive: true, mode: 0o700 });
+        const entries = readdirSync(srcPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const entrySrc = join(srcPath, entry.name);
+            const entryDest = join(destPath, entry.name);
+            // First check: Skip symlinks for security
+            if (entry.isSymbolicLink()) {
+                warnings.push(`Skipped symlink: ${entry.name}`);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                copyRecursive(entrySrc, entryDest);
+            }
+            else if (entry.isFile()) {
+                // SECURITY: Second check immediately before copy to minimize TOCTOU window
+                // This doesn't eliminate the race but significantly reduces the attack window
+                try {
+                    const stat = lstatSync(entrySrc);
+                    if (stat.isSymbolicLink()) {
+                        warnings.push(`Skipped symlink (detected on copy): ${entry.name}`);
+                        continue;
+                    }
+                    cpSync(entrySrc, entryDest);
+                }
+                catch (err) {
+                    // File may have been removed/changed between readdir and copy
+                    warnings.push(`Could not copy ${entry.name}: ${err instanceof Error ? err.message : 'unknown error'}`);
+                }
+            }
+        }
+    }
+    copyRecursive(src, dest);
+    return { warnings };
+}
+/**
+ * Download and install a skill to multiple agent directories.
+ *
+ * @param owner - GitHub repository owner
+ * @param repo - GitHub repository name
+ * @param skillPath - Path to skill within repository (or SKILL.md for root)
+ * @param skillName - Name to use for the installed skill directory
+ * @param agents - List of agents to install to
+ * @param options - Installation options (force, baseDir)
+ * @returns InstallResult with details of what was installed/skipped
+ */
+export async function installSkill(owner, repo, skillPath, skillName, agents, options) {
+    const result = {
+        installed: [],
+        skipped: [],
+        warnings: [],
+        failed: false,
+    };
+    const { force, baseDir } = options;
+    const tmpDir = join(homedir(), '.cache', 'skillfish', `${owner}-${repo}-${randomUUID()}`);
+    mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    try {
+        // Download skill
+        const downloadPath = skillPath === SKILL_FILENAME ? '' : skillPath;
+        const degitPath = downloadPath ? `${owner}/${repo}/${downloadPath}` : `${owner}/${repo}`;
+        const emitter = degit(degitPath, { cache: false, force: true });
+        await emitter.clone(tmpDir);
+        // Validate download
+        const skillMdPath = join(tmpDir, SKILL_FILENAME);
+        if (!existsSync(skillMdPath)) {
+            throw new SkillMdNotFoundError(skillPath);
+        }
+        // Copy to each agent directory
+        for (const agent of agents) {
+            const destDir = join(baseDir, agent.dir, skillName);
+            if (existsSync(destDir) && !force) {
+                result.skipped.push({
+                    skill: skillName,
+                    agent: agent.name,
+                    reason: 'Already exists (use --force to overwrite)',
+                });
+                continue;
+            }
+            // Create parent directory and remove existing if force
+            mkdirSync(join(baseDir, agent.dir), { recursive: true, mode: 0o700 });
+            if (existsSync(destDir)) {
+                rmSync(destDir, { recursive: true });
+            }
+            // Use safe copy to skip symlinks (security: prevents symlink attacks)
+            const copyResult = safeCopyDir(tmpDir, destDir);
+            result.warnings.push(...copyResult.warnings.map((w) => `${skillName}: ${w}`));
+            result.installed.push({
+                skill: skillName,
+                agent: agent.name,
+                path: destDir,
+            });
+        }
+    }
+    catch (err) {
+        result.failed = true;
+        if (err instanceof SkillMdNotFoundError) {
+            result.failureReason = err.message;
+        }
+        else {
+            result.failureReason = err instanceof Error ? err.message : String(err);
+        }
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    return result;
+}
+/**
+ * List installed skills for a given agent directory.
+ *
+ * @param skillDir - Path to the agent's skills directory
+ * @returns Array of skill names that have a valid SKILL.md
+ */
+export function listInstalledSkillsInDir(skillDir) {
+    if (!existsSync(skillDir)) {
+        return [];
+    }
+    try {
+        return readdirSync(skillDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .filter((entry) => existsSync(join(skillDir, entry.name, SKILL_FILENAME)))
+            .map((entry) => entry.name);
+    }
+    catch {
+        // Directory might not be readable
+        return [];
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Track a skill install. Fire-and-forget - never blocks or throws.
+ *
+ * NOTE: Due to Node.js event loop behavior, this request may not complete
+ * if the CLI process exits immediately after calling. This is acceptable
+ * for directional metrics (like npm download counts).
+ *
+ * @param github Full GitHub path (e.g., owner/repo/path/to/skill)
+ */
+export declare function trackInstall(github: string): void;

package/dist/telemetry.js

@@ -0,0 +1,27 @@
+const TELEMETRY_URL = 'https://mcpmarket.com/api/telemetry';
+/**
+ * Track a skill install. Fire-and-forget - never blocks or throws.
+ *
+ * NOTE: Due to Node.js event loop behavior, this request may not complete
+ * if the CLI process exits immediately after calling. This is acceptable
+ * for directional metrics (like npm download counts).
+ *
+ * @param github Full GitHub path (e.g., owner/repo/path/to/skill)
+ */
+export function trackInstall(github) {
+    try {
+        if (process.env.DO_NOT_TRACK === '1' || process.env.CI === 'true')
+            return;
+        if (!github || github.length > 500)
+            return;
+        // POST with JSON body - fire and forget
+        fetch(TELEMETRY_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ github }),
+        }).catch(() => { });
+    }
+    catch {
+        // Telemetry should never throw
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Utility functions for skillfish CLI.
+ * These are pure functions extracted for testability.
+ */
+/**
+ * Validates a path to prevent directory traversal attacks.
+ * Ensures path doesn't escape the intended directory.
+ */
+export declare function isValidPath(pathStr: string): boolean;
+/**
+ * Type for GitHub tree API item.
+ */
+export type GitTreeItem = {
+    path: string;
+    type: string;
+    mode?: string;
+    sha?: string;
+    size?: number;
+    url?: string;
+};
+/**
+ * Type for GitHub tree API response.
+ */
+export type GitTreeResponse = {
+    tree?: GitTreeItem[];
+    sha?: string;
+    url?: string;
+    truncated?: boolean;
+};
+/**
+ * Type guard for GitHub tree API response.
+ * Validates the response structure at runtime.
+ */
+export declare function isGitTreeResponse(data: unknown): data is GitTreeResponse;
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Extracts name and description fields with fallbacks.
+ */
+export declare function parseFrontmatter(content: string): {
+    name?: string;
+    description?: string;
+};
+/**
+ * Derive skill name from path and repo name.
+ */
+export declare function deriveSkillName(skillPath: string, repoName: string): string;
+/**
+ * Convert kebab-case or snake_case to Title Case.
+ * "skill-lookup" → "Skill Lookup"
+ * "my_cool_skill" → "My Cool Skill"
+ */
+export declare function toTitleCase(str: string): string;
+/**
+ * Truncate text to a maximum length, adding ellipsis if needed.
+ */
+export declare function truncate(text: string, maxLength: number): string;
+/**
+ * Extract SKILL.md paths from validated GitHub tree response.
+ */
+export declare function extractSkillPaths(data: GitTreeResponse, skillFilename?: string): string[];
+/**
+ * Sleep for a specified duration.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Process items with bounded concurrency.
+ * Prevents overwhelming resources with unbounded parallel requests.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param concurrency - Maximum concurrent operations (default: 10)
+ */
+export declare function batchMap<T, R>(items: T[], fn: (item: T) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * Common installed skill structure used across commands.
+ */
+export interface InstalledSkill {
+    skill: string;
+    agent: string;
+    path: string;
+    location?: 'global' | 'project';
+}
+/**
+ * Base JSON output with fields common to all commands.
+ * All command-specific types extend this for API consistency.
+ */
+export interface BaseJsonOutput {
+    success: boolean;
+    exit_code?: number;
+    errors: string[];
+}
+/**
+ * JSON output for the `add` command.
+ */
+export interface AddJsonOutput extends BaseJsonOutput {
+    installed: InstalledSkill[];
+    skipped: Array<{
+        skill: string;
+        agent: string;
+        reason: string;
+    }>;
+    skills_found?: string[];
+}
+/**
+ * JSON output for the `list` command.
+ */
+export interface ListJsonOutput extends BaseJsonOutput {
+    installed: InstalledSkill[];
+    agents_detected: string[];
+}
+/**
+ * JSON output for the `remove` command.
+ */
+export interface RemoveJsonOutput extends BaseJsonOutput {
+    removed: InstalledSkill[];
+}
+/** @deprecated Use AddJsonOutput instead */
+export type JsonOutput = AddJsonOutput;
+/**
+ * Create a fresh JSON output object for the add command.
+ */
+export declare function createJsonOutput(): AddJsonOutput;
+/**
+ * Check if stdout is a TTY (interactive terminal).
+ */
+export declare function isTTY(): boolean;
+/**
+ * Check if stdin is a TTY (interactive terminal).
+ */
+export declare function isInputTTY(): boolean;

package/dist/utils.js

@@ -0,0 +1,163 @@
+/**
+ * Utility functions for skillfish CLI.
+ * These are pure functions extracted for testability.
+ */
+import { normalize, isAbsolute, basename } from 'path';
+/**
+ * Validates a path to prevent directory traversal attacks.
+ * Ensures path doesn't escape the intended directory.
+ */
+export function isValidPath(pathStr) {
+    // Reject absolute paths
+    if (isAbsolute(pathStr))
+        return false;
+    // Normalize and check for directory traversal
+    const normalized = normalize(pathStr);
+    if (normalized.startsWith('..') || normalized.includes('/../'))
+        return false;
+    // Only allow alphanumeric, dots, hyphens, underscores, and forward slashes
+    if (!/^[\w./-]+$/.test(pathStr))
+        return false;
+    // Reject paths that could be problematic
+    if (pathStr.includes('//') || pathStr.startsWith('/'))
+        return false;
+    return true;
+}
+/**
+ * Type guard for GitHub tree API response.
+ * Validates the response structure at runtime.
+ */
+export function isGitTreeResponse(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const obj = data;
+    // tree is optional, but if present must be an array
+    if ('tree' in obj && obj.tree !== undefined) {
+        if (!Array.isArray(obj.tree))
+            return false;
+        // Validate each item has required fields
+        for (const item of obj.tree) {
+            if (typeof item !== 'object' || item === null)
+                return false;
+            const entry = item;
+            if (typeof entry.path !== 'string')
+                return false;
+            if (typeof entry.type !== 'string')
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Extracts name and description fields with fallbacks.
+ */
+export function parseFrontmatter(content) {
+    // Match frontmatter block: ---\n...\n---
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const yaml = match[1];
+    // Extract name (handles quoted and unquoted values)
+    const nameMatch = yaml.match(/^name:\s*["']?(.+?)["']?\s*$/m);
+    const name = nameMatch?.[1]?.trim();
+    // Extract description (handles quoted and unquoted values)
+    const descMatch = yaml.match(/^description:\s*["']?(.+?)["']?\s*$/m);
+    const description = descMatch?.[1]?.trim();
+    return { name, description };
+}
+/**
+ * Derive skill name from path and repo name.
+ */
+export function deriveSkillName(skillPath, repoName) {
+    if (skillPath === 'SKILL.md' || skillPath === './SKILL.md') {
+        return repoName;
+    }
+    const normalized = skillPath.replace(/\/SKILL\.md$/i, '');
+    const name = basename(normalized);
+    if (!/^[\w.-]+$/.test(name)) {
+        return repoName;
+    }
+    return name;
+}
+/**
+ * Convert kebab-case or snake_case to Title Case.
+ * "skill-lookup" → "Skill Lookup"
+ * "my_cool_skill" → "My Cool Skill"
+ */
+export function toTitleCase(str) {
+    return str
+        .replace(/[-_]/g, ' ')
+        .replace(/\b\w/g, char => char.toUpperCase());
+}
+/**
+ * Truncate text to a maximum length, adding ellipsis if needed.
+ */
+export function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength - 1).trim() + '…';
+}
+/**
+ * Extract SKILL.md paths from validated GitHub tree response.
+ */
+export function extractSkillPaths(data, skillFilename = 'SKILL.md') {
+    if (!data.tree)
+        return [];
+    return data.tree
+        .filter(item => item.type === 'blob' && item.path.endsWith(skillFilename))
+        .map(item => item.path);
+}
+/**
+ * Sleep for a specified duration.
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Process items with bounded concurrency.
+ * Prevents overwhelming resources with unbounded parallel requests.
+ *
+ * @param items - Items to process
+ * @param fn - Async function to apply to each item
+ * @param concurrency - Maximum concurrent operations (default: 10)
+ */
+export async function batchMap(items, fn, concurrency = 10) {
+    const results = [];
+    let index = 0;
+    async function worker() {
+        while (index < items.length) {
+            const currentIndex = index++;
+            results[currentIndex] = await fn(items[currentIndex]);
+        }
+    }
+    // Start workers up to concurrency limit
+    const workers = Array(Math.min(concurrency, items.length))
+        .fill(null)
+        .map(() => worker());
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Create a fresh JSON output object for the add command.
+ */
+export function createJsonOutput() {
+    return {
+        success: true,
+        installed: [],
+        skipped: [],
+        errors: [],
+    };
+}
+/**
+ * Check if stdout is a TTY (interactive terminal).
+ */
+export function isTTY() {
+    return process.stdout.isTTY === true;
+}
+/**
+ * Check if stdin is a TTY (interactive terminal).
+ */
+export function isInputTTY() {
+    return process.stdin.isTTY === true;
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "skillfish",
+  "version": "1.0.0",
+  "description": "Install AI agent skills from GitHub with a single command",
+  "type": "module",
+  "bin": {
+    "skillfish": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nichochar/skillfish.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nichochar/skillfish/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "cli",
+    "skills",
+    "agent-skills",
+    "ai-agent",
+    "ai-tools",
+    "mcp",
+    "claude",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "codex",
+    "copilot",
+    "github-copilot",
+    "gemini-cli",
+    "opencode",
+    "goose",
+    "amp",
+    "roo",
+    "kiro",
+    "trae",
+    "cline"
+  ],
+  "author": "Graeme Knox",
+  "license": "AGPL-3.0",
+  "homepage": "https://skill.fish",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "commander": "^14.0.2",
+    "degit": "^2.8.4",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.17"
+  }
+}