@skilljack/mcp 0.6.0 → 0.7.1

package/dist/github-config.js

@@ -0,0 +1,191 @@
+/**
+ * GitHub configuration parsing and URL detection.
+ * Handles detection of GitHub URLs, parsing repo specs, and allowlist validation.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Default polling interval: 5 minutes.
+ */
+const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Default cache directory.
+ */
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".skilljack", "github-cache");
+/**
+ * Check if a path is a GitHub URL.
+ * Detects paths containing "github.com".
+ */
+export function isGitHubUrl(urlOrPath) {
+    return urlOrPath.toLowerCase().includes("github.com");
+}
+/**
+ * Parse a GitHub URL into a GitHubRepoSpec.
+ *
+ * Supported formats:
+ *   github.com/owner/repo
+ *   github.com/owner/repo@ref
+ *   github.com/owner/repo/subpath
+ *   github.com/owner/repo/subpath@ref
+ *   https://github.com/owner/repo
+ *   https://github.com/owner/repo.git
+ *
+ * @param url - The GitHub URL to parse
+ * @returns Parsed GitHubRepoSpec
+ * @throws Error if URL format is invalid
+ */
+export function parseGitHubUrl(url) {
+    // Remove protocol prefix if present
+    let normalized = url.replace(/^https?:\/\//, "");
+    // Remove github.com prefix
+    normalized = normalized.replace(/^github\.com\//i, "");
+    // Remove trailing .git if present
+    normalized = normalized.replace(/\.git$/, "");
+    // Extract ref if present (everything after @)
+    let ref;
+    const atIndex = normalized.lastIndexOf("@");
+    if (atIndex !== -1) {
+        ref = normalized.slice(atIndex + 1);
+        normalized = normalized.slice(0, atIndex);
+    }
+    // Split remaining path: owner/repo[/subpath...]
+    let parts = normalized.split("/").filter((p) => p.length > 0);
+    if (parts.length < 2) {
+        throw new Error(`Invalid GitHub URL: "${url}". Expected format: github.com/owner/repo[/subpath][@ref]`);
+    }
+    const owner = parts[0];
+    const repo = parts[1];
+    // Handle GitHub web URLs with /tree/<ref>/ or /blob/<ref>/ patterns
+    // e.g., owner/repo/tree/main/path/to/dir -> extract ref and subpath
+    if (parts.length >= 4 && (parts[2] === "tree" || parts[2] === "blob")) {
+        // parts[2] is "tree" or "blob", parts[3] is the ref
+        if (!ref) {
+            ref = parts[3];
+        }
+        // Everything after the ref is the subpath
+        const subpath = parts.length > 4 ? parts.slice(4).join("/") : undefined;
+        return { owner, repo, ref, subpath };
+    }
+    const subpath = parts.length > 2 ? parts.slice(2).join("/") : undefined;
+    return { owner, repo, ref, subpath };
+}
+/**
+ * Check if a repository is allowed by the allowlist.
+ * If no allowlist is configured (both allowedOrgs and allowedUsers empty),
+ * all repos are DENIED by default for security.
+ *
+ * @param spec - The repository specification
+ * @param config - GitHub configuration with allowlists
+ * @returns true if allowed, false if blocked
+ */
+export function isRepoAllowed(spec, config) {
+    // If no allowlist configured, deny all for security
+    if (config.allowedOrgs.length === 0 && config.allowedUsers.length === 0) {
+        return false;
+    }
+    const ownerLower = spec.owner.toLowerCase();
+    // Check if owner is in allowed orgs
+    if (config.allowedOrgs.some((org) => org.toLowerCase() === ownerLower)) {
+        return true;
+    }
+    // Check if owner is in allowed users
+    if (config.allowedUsers.some((user) => user.toLowerCase() === ownerLower)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Parse a comma-separated list from an environment variable.
+ */
+function parseCommaList(envValue) {
+    if (!envValue) {
+        return [];
+    }
+    return envValue
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Path to the config file.
+ */
+const CONFIG_FILE_PATH = path.join(os.homedir(), ".skilljack", "config.json");
+/**
+ * Load allowlist from config file.
+ * Returns empty arrays if file doesn't exist or can't be parsed.
+ */
+function loadAllowlistFromConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE_PATH)) {
+            const content = fs.readFileSync(CONFIG_FILE_PATH, "utf-8");
+            const config = JSON.parse(content);
+            return {
+                orgs: Array.isArray(config.githubAllowedOrgs) ? config.githubAllowedOrgs : [],
+                users: Array.isArray(config.githubAllowedUsers) ? config.githubAllowedUsers : [],
+            };
+        }
+    }
+    catch {
+        // Ignore errors reading config file
+    }
+    return { orgs: [], users: [] };
+}
+/**
+ * Get GitHub configuration from environment variables and config file.
+ * Environment variables take precedence over config file.
+ *
+ * Environment variables:
+ *   GITHUB_TOKEN - Authentication token for private repos
+ *   GITHUB_POLL_INTERVAL_MS - Polling interval (0 to disable, default 300000)
+ *   SKILLJACK_CACHE_DIR - Cache directory (default ~/.skilljack/github-cache)
+ *   GITHUB_ALLOWED_ORGS - Comma-separated list of allowed organizations (overrides config)
+ *   GITHUB_ALLOWED_USERS - Comma-separated list of allowed users (overrides config)
+ */
+export function getGitHubConfig() {
+    const pollIntervalStr = process.env.GITHUB_POLL_INTERVAL_MS;
+    let pollIntervalMs = DEFAULT_POLL_INTERVAL_MS;
+    if (pollIntervalStr !== undefined) {
+        const parsed = parseInt(pollIntervalStr, 10);
+        if (!isNaN(parsed) && parsed >= 0) {
+            pollIntervalMs = parsed;
+        }
+    }
+    // Load allowlist from config file as fallback
+    const configAllowlist = loadAllowlistFromConfig();
+    // Environment variables override config file
+    const envOrgs = parseCommaList(process.env.GITHUB_ALLOWED_ORGS);
+    const envUsers = parseCommaList(process.env.GITHUB_ALLOWED_USERS);
+    return {
+        token: process.env.GITHUB_TOKEN,
+        pollIntervalMs,
+        cacheDir: process.env.SKILLJACK_CACHE_DIR || DEFAULT_CACHE_DIR,
+        allowedOrgs: envOrgs.length > 0 ? envOrgs : configAllowlist.orgs,
+        allowedUsers: envUsers.length > 0 ? envUsers : configAllowlist.users,
+    };
+}
+/**
+ * Get the local cache path for a GitHub repository.
+ *
+ * @param spec - The repository specification
+ * @param cacheDir - Base cache directory
+ * @returns Full path to the cached repository (including subpath if specified)
+ */
+export function getRepoCachePath(spec, cacheDir) {
+    const repoPath = path.join(cacheDir, spec.owner, spec.repo);
+    if (spec.subpath) {
+        return path.join(repoPath, spec.subpath);
+    }
+    return repoPath;
+}
+/**
+ * Get the local clone path for a GitHub repository (without subpath).
+ * This is where the git repository is cloned to.
+ *
+ * @param spec - The repository specification
+ * @param cacheDir - Base cache directory
+ * @returns Full path to the cloned repository root
+ */
+export function getRepoClonePath(spec, cacheDir) {
+    return path.join(cacheDir, spec.owner, spec.repo);
+}

package/dist/github-polling.d.ts

@@ -0,0 +1,35 @@
+/**
+ * GitHub repository polling for updates.
+ * Periodically checks for changes and triggers sync when updates are available.
+ */
+import { GitHubRepoSpec } from "./github-config.js";
+import { SyncOptions, SyncResult } from "./github-sync.js";
+/**
+ * Options for the polling manager.
+ */
+export interface PollingOptions {
+    intervalMs: number;
+    onUpdate: (spec: GitHubRepoSpec, result: SyncResult) => void;
+    onError?: (spec: GitHubRepoSpec, error: Error) => void;
+}
+/**
+ * Polling manager interface.
+ */
+export interface PollingManager {
+    start(): void;
+    stop(): void;
+    checkNow(): Promise<void>;
+    isRunning(): boolean;
+}
+/**
+ * Create a polling manager for GitHub repositories.
+ *
+ * The manager periodically checks for updates and syncs repositories
+ * when changes are detected. Pinned refs (tags, commits) are skipped.
+ *
+ * @param specs - Repository specifications to poll
+ * @param syncOptions - Options for sync operations
+ * @param pollingOptions - Polling configuration
+ * @returns Polling manager
+ */
+export declare function createPollingManager(specs: GitHubRepoSpec[], syncOptions: SyncOptions, pollingOptions: PollingOptions): PollingManager;

package/dist/github-polling.js

@@ -0,0 +1,108 @@
+/**
+ * GitHub repository polling for updates.
+ * Periodically checks for changes and triggers sync when updates are available.
+ */
+import { syncRepo, hasRemoteUpdates } from "./github-sync.js";
+/**
+ * Create a polling manager for GitHub repositories.
+ *
+ * The manager periodically checks for updates and syncs repositories
+ * when changes are detected. Pinned refs (tags, commits) are skipped.
+ *
+ * @param specs - Repository specifications to poll
+ * @param syncOptions - Options for sync operations
+ * @param pollingOptions - Polling configuration
+ * @returns Polling manager
+ */
+export function createPollingManager(specs, syncOptions, pollingOptions) {
+    let intervalId = null;
+    let isChecking = false;
+    /**
+     * Filter specs to only include those that should be polled.
+     * Pinned refs (tags, commits) are excluded.
+     */
+    function getPolledSpecs() {
+        return specs.filter((spec) => {
+            if (!spec.ref) {
+                return true; // No ref means default branch, poll it
+            }
+            // Exclude what looks like a tag version or commit hash
+            const isVersionTag = /^v?\d+(\.\d+)*/.test(spec.ref);
+            const isCommitHash = /^[0-9a-f]{7,40}$/i.test(spec.ref);
+            return !isVersionTag && !isCommitHash;
+        });
+    }
+    /**
+     * Check all repositories for updates.
+     */
+    async function checkForUpdates() {
+        if (isChecking) {
+            console.error("Polling: Already checking for updates, skipping...");
+            return;
+        }
+        isChecking = true;
+        const polledSpecs = getPolledSpecs();
+        if (polledSpecs.length === 0) {
+            console.error("Polling: No repositories to poll (all pinned to specific refs)");
+            isChecking = false;
+            return;
+        }
+        console.error(`Polling: Checking ${polledSpecs.length} repo(s) for updates...`);
+        for (const spec of polledSpecs) {
+            try {
+                const hasUpdates = await hasRemoteUpdates(spec, syncOptions);
+                if (hasUpdates) {
+                    console.error(`Polling: Updates available for ${spec.owner}/${spec.repo}`);
+                    const result = await syncRepo(spec, syncOptions);
+                    if (!result.error && result.updated) {
+                        pollingOptions.onUpdate(spec, result);
+                    }
+                }
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                console.error(`Polling: Error checking ${spec.owner}/${spec.repo}: ${err.message}`);
+                pollingOptions.onError?.(spec, err);
+            }
+        }
+        isChecking = false;
+    }
+    return {
+        start() {
+            if (intervalId !== null) {
+                console.error("Polling: Already running");
+                return;
+            }
+            if (pollingOptions.intervalMs <= 0) {
+                console.error("Polling: Disabled (interval <= 0)");
+                return;
+            }
+            const polledSpecs = getPolledSpecs();
+            if (polledSpecs.length === 0) {
+                console.error("Polling: Not starting (all repos pinned to specific refs)");
+                return;
+            }
+            console.error(`Polling: Starting with ${pollingOptions.intervalMs}ms interval ` +
+                `for ${polledSpecs.length} repo(s)`);
+            intervalId = setInterval(() => {
+                checkForUpdates().catch((error) => {
+                    console.error(`Polling: Unexpected error: ${error}`);
+                });
+            }, pollingOptions.intervalMs);
+        },
+        stop() {
+            if (intervalId === null) {
+                return;
+            }
+            console.error("Polling: Stopping");
+            clearInterval(intervalId);
+            intervalId = null;
+        },
+        async checkNow() {
+            await checkForUpdates();
+        },
+        isRunning() {
+            return intervalId !== null;
+        },
+    };
+}

package/dist/github-sync.d.ts

@@ -0,0 +1,49 @@
+/**
+ * GitHub repository synchronization.
+ * Handles cloning and pulling repositories to local cache.
+ */
+import { GitHubRepoSpec } from "./github-config.js";
+/**
+ * Options for syncing GitHub repositories.
+ */
+export interface SyncOptions {
+    cacheDir: string;
+    token?: string;
+    shallowClone?: boolean;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface SyncResult {
+    spec: GitHubRepoSpec;
+    localPath: string;
+    clonePath: string;
+    updated: boolean;
+    error?: string;
+}
+/**
+ * Sync a single GitHub repository.
+ * Clones if not present, pulls if already cloned.
+ *
+ * @param spec - Repository specification
+ * @param options - Sync options
+ * @returns Sync result
+ */
+export declare function syncRepo(spec: GitHubRepoSpec, options: SyncOptions): Promise<SyncResult>;
+/**
+ * Sync multiple GitHub repositories.
+ *
+ * @param specs - Repository specifications
+ * @param options - Sync options
+ * @returns Array of sync results
+ */
+export declare function syncAllRepos(specs: GitHubRepoSpec[], options: SyncOptions): Promise<SyncResult[]>;
+/**
+ * Check if a repository has remote updates available.
+ * Uses git fetch --dry-run to check without downloading.
+ *
+ * @param spec - Repository specification
+ * @param options - Sync options
+ * @returns true if updates are available
+ */
+export declare function hasRemoteUpdates(spec: GitHubRepoSpec, options: SyncOptions): Promise<boolean>;

package/dist/github-sync.js

@@ -0,0 +1,259 @@
+/**
+ * GitHub repository synchronization.
+ * Handles cloning and pulling repositories to local cache.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { simpleGit } from "simple-git";
+import { getRepoClonePath, getRepoCachePath } from "./github-config.js";
+/**
+ * Maximum retry attempts for network operations.
+ */
+const MAX_RETRIES = 3;
+/**
+ * Initial backoff delay in milliseconds.
+ */
+const INITIAL_BACKOFF_MS = 1000;
+/**
+ * Sleep for a given number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Build the HTTPS URL for a GitHub repository.
+ * Includes token for authentication if provided.
+ */
+function buildRepoUrl(spec, token) {
+    if (token) {
+        return `https://${token}@github.com/${spec.owner}/${spec.repo}.git`;
+    }
+    return `https://github.com/${spec.owner}/${spec.repo}.git`;
+}
+/**
+ * Ensure the parent directory exists.
+ */
+function ensureParentDir(filePath) {
+    const parentDir = path.dirname(filePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+}
+/**
+ * Check if a directory is a git repository.
+ */
+function isGitRepo(dir) {
+    return fs.existsSync(path.join(dir, ".git"));
+}
+/**
+ * Clone a repository with retry logic.
+ */
+async function cloneWithRetry(git, url, destPath, ref, shallowClone) {
+    const cloneOptions = [];
+    if (shallowClone) {
+        cloneOptions.push("--depth", "1");
+    }
+    if (ref) {
+        cloneOptions.push("--branch", ref);
+    }
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            await git.clone(url, destPath, cloneOptions);
+            return;
+        }
+        catch (error) {
+            const isLastAttempt = attempt === MAX_RETRIES - 1;
+            if (isLastAttempt) {
+                throw error;
+            }
+            const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+            console.error(`Clone attempt ${attempt + 1}/${MAX_RETRIES} failed, retrying in ${backoff}ms...`);
+            await sleep(backoff);
+        }
+    }
+}
+/**
+ * Pull updates with retry logic.
+ * Returns true if there were changes.
+ */
+async function pullWithRetry(git, ref) {
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            // Get current HEAD before pull
+            const beforeHead = await git.revparse(["HEAD"]);
+            // Pull changes
+            if (ref) {
+                await git.fetch(["origin", ref]);
+                await git.checkout(ref);
+                await git.pull("origin", ref, ["--ff-only"]);
+            }
+            else {
+                await git.pull(["--ff-only"]);
+            }
+            // Check if HEAD changed
+            const afterHead = await git.revparse(["HEAD"]);
+            return beforeHead !== afterHead;
+        }
+        catch (error) {
+            const isLastAttempt = attempt === MAX_RETRIES - 1;
+            if (isLastAttempt) {
+                throw error;
+            }
+            const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+            console.error(`Pull attempt ${attempt + 1}/${MAX_RETRIES} failed, retrying in ${backoff}ms...`);
+            await sleep(backoff);
+        }
+    }
+    return false;
+}
+/**
+ * Sync a single GitHub repository.
+ * Clones if not present, pulls if already cloned.
+ *
+ * @param spec - Repository specification
+ * @param options - Sync options
+ * @returns Sync result
+ */
+export async function syncRepo(spec, options) {
+    const clonePath = getRepoClonePath(spec, options.cacheDir);
+    const localPath = getRepoCachePath(spec, options.cacheDir);
+    const shallowClone = options.shallowClone !== false; // Default true
+    const result = {
+        spec,
+        localPath,
+        clonePath,
+        updated: false,
+    };
+    try {
+        const url = buildRepoUrl(spec, options.token);
+        const git = simpleGit();
+        if (!isGitRepo(clonePath)) {
+            // Clone the repository
+            console.error(`Cloning ${spec.owner}/${spec.repo}...`);
+            ensureParentDir(clonePath);
+            await cloneWithRetry(git, url, clonePath, spec.ref, shallowClone);
+            result.updated = true;
+            console.error(`Cloned ${spec.owner}/${spec.repo} to ${clonePath}`);
+        }
+        else {
+            // Pull updates
+            console.error(`Pulling updates for ${spec.owner}/${spec.repo}...`);
+            const repoGit = simpleGit(clonePath);
+            // For pinned refs (tags/commits), we don't pull updates
+            if (spec.ref && !spec.ref.includes("/")) {
+                // Check if this looks like a tag or commit hash
+                const isTag = await repoGit
+                    .tags()
+                    .then((tags) => tags.all.includes(spec.ref))
+                    .catch(() => false);
+                const isCommit = /^[0-9a-f]{7,40}$/i.test(spec.ref);
+                if (isTag || isCommit) {
+                    console.error(`Skipping pull for pinned ref: ${spec.ref}`);
+                    return result;
+                }
+            }
+            result.updated = await pullWithRetry(repoGit, spec.ref);
+            if (result.updated) {
+                console.error(`Updated ${spec.owner}/${spec.repo}`);
+            }
+            else {
+                console.error(`${spec.owner}/${spec.repo} is up to date`);
+            }
+        }
+        // Verify the subpath exists if specified
+        if (spec.subpath && !fs.existsSync(localPath)) {
+            result.error = `Subpath "${spec.subpath}" not found in repository`;
+            console.error(`Warning: ${result.error}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide helpful error messages
+        if (errorMessage.includes("Authentication failed") || errorMessage.includes("403")) {
+            result.error = `Authentication failed for ${spec.owner}/${spec.repo}. For private repos, set GITHUB_TOKEN environment variable.`;
+        }
+        else if (errorMessage.includes("rate limit")) {
+            result.error = `Rate limited when accessing ${spec.owner}/${spec.repo}. Try again later.`;
+        }
+        else if (errorMessage.includes("not found") || errorMessage.includes("404")) {
+            result.error = `Repository not found: ${spec.owner}/${spec.repo}`;
+        }
+        else {
+            result.error = `Failed to sync ${spec.owner}/${spec.repo}: ${errorMessage}`;
+        }
+        console.error(result.error);
+    }
+    return result;
+}
+/**
+ * Sync multiple GitHub repositories.
+ *
+ * @param specs - Repository specifications
+ * @param options - Sync options
+ * @returns Array of sync results
+ */
+export async function syncAllRepos(specs, options) {
+    const results = [];
+    for (const spec of specs) {
+        const result = await syncRepo(spec, options);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * Check if a repository has remote updates available.
+ * Uses git fetch --dry-run to check without downloading.
+ *
+ * @param spec - Repository specification
+ * @param options - Sync options
+ * @returns true if updates are available
+ */
+export async function hasRemoteUpdates(spec, options) {
+    const clonePath = getRepoClonePath(spec, options.cacheDir);
+    if (!isGitRepo(clonePath)) {
+        // Not cloned yet, so yes there are "updates"
+        return true;
+    }
+    // Skip check for pinned refs
+    if (spec.ref) {
+        const git = simpleGit(clonePath);
+        const isTag = await git
+            .tags()
+            .then((tags) => tags.all.includes(spec.ref))
+            .catch(() => false);
+        const isCommit = /^[0-9a-f]{7,40}$/i.test(spec.ref);
+        if (isTag || isCommit) {
+            return false;
+        }
+    }
+    try {
+        const git = simpleGit(clonePath);
+        const url = buildRepoUrl(spec, options.token);
+        // Fetch to update remote refs
+        await git.fetch(["origin"]);
+        // Compare local and remote
+        const localHead = await git.revparse(["HEAD"]);
+        const remoteRef = spec.ref ? `origin/${spec.ref}` : "origin/HEAD";
+        try {
+            const remoteHead = await git.revparse([remoteRef]);
+            return localHead !== remoteHead;
+        }
+        catch {
+            // Remote ref might not exist, try origin/main or origin/master
+            for (const branch of ["origin/main", "origin/master"]) {
+                try {
+                    const remoteHead = await git.revparse([branch]);
+                    return localHead !== remoteHead;
+                }
+                catch {
+                    continue;
+                }
+            }
+            return false;
+        }
+    }
+    catch (error) {
+        console.error(`Failed to check for updates: ${error}`);
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -6,8 +6,17 @@
  * Provides global skills with tools for progressive disclosure.
  *
  * Usage:
- *   skilljack-mcp /path/to/skills [/path2 ...]   # One or more directories
- *   SKILLS_DIR=/path/to/skills skilljack-mcp    # Single directory via env
- *   SKILLS_DIR=/path1,/path2 skilljack-mcp      # Multiple (comma-separated)
+ *   skilljack-mcp /path/to/skills [/path2 ...]           # Local directories
+ *   skilljack-mcp --static /path/to/skills               # Static mode (no file watching)
+ *   skilljack-mcp github.com/owner/repo                  # GitHub repository
+ *   skilljack-mcp /local github.com/owner/repo           # Mixed local + GitHub
+ *   SKILLS_DIR=/path,github.com/owner/repo skilljack-mcp # Via environment
+ *   SKILLJACK_STATIC=true skilljack-mcp                  # Static mode via env
+ *   (or configure local directories via the skill-config UI)
+ *
+ * Options:
+ *   --static  Freeze skills list at startup. Disables file watching and
+ *             tools/prompts listChanged notifications. Resource subscriptions
+ *             remain fully dynamic.
  */
 export {};