@skilljack/mcp 0.7.0 → 0.7.1

package/dist/github-config.d.ts

@@ -0,0 +1,83 @@
+/**
+ * GitHub configuration parsing and URL detection.
+ * Handles detection of GitHub URLs, parsing repo specs, and allowlist validation.
+ */
+/**
+ * Parsed GitHub repository specification.
+ */
+export interface GitHubRepoSpec {
+    owner: string;
+    repo: string;
+    ref?: string;
+    subpath?: string;
+}
+/**
+ * GitHub-specific configuration from environment variables.
+ */
+export interface GitHubConfig {
+    token?: string;
+    pollIntervalMs: number;
+    cacheDir: string;
+    allowedOrgs: string[];
+    allowedUsers: string[];
+}
+/**
+ * Check if a path is a GitHub URL.
+ * Detects paths containing "github.com".
+ */
+export declare function isGitHubUrl(urlOrPath: string): boolean;
+/**
+ * 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 declare function parseGitHubUrl(url: string): GitHubRepoSpec;
+/**
+ * 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 declare function isRepoAllowed(spec: GitHubRepoSpec, config: GitHubConfig): boolean;
+/**
+ * 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 declare function getGitHubConfig(): GitHubConfig;
+/**
+ * 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 declare function getRepoCachePath(spec: GitHubRepoSpec, cacheDir: string): string;
+/**
+ * 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 declare function getRepoClonePath(spec: GitHubRepoSpec, cacheDir: string): string;

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>;