@sentry/warden 0.1.1 → 0.3.0

package/src/skills/remote.ts

@@ -1,604 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, renameSync, readdirSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { execFileSync } from 'node:child_process';
-import { z } from 'zod';
-import { loadSkillFromMarkdown, SkillLoaderError } from './loader.js';
-import type { SkillDefinition } from '../config/schema.js';
-
-/** Default TTL for unpinned remote skills: 24 hours */
-const DEFAULT_TTL_SECONDS = 86400;
-
-/** Schema for a single remote entry in state.json */
-const RemoteEntrySchema = z.object({
-  sha: z.string(),
-  fetchedAt: z.string().datetime(),
-});
-
-/** Schema for the entire state.json file */
-const RemoteStateSchema = z.object({
-  remotes: z.record(z.string(), RemoteEntrySchema),
-});
-
-export type RemoteEntry = z.infer<typeof RemoteEntrySchema>;
-export type RemoteState = z.infer<typeof RemoteStateSchema>;
-
-/** Schema for a plugin in marketplace.json */
-const MarketplacePluginSchema = z.object({
-  name: z.string(),
-  source: z.string(),
-  description: z.string().optional(),
-  category: z.string().optional(),
-});
-
-/** Schema for .claude-plugin/marketplace.json */
-const MarketplaceConfigSchema = z.object({
-  $schema: z.string().optional(),
-  name: z.string(),
-  description: z.string().optional(),
-  plugins: z.array(MarketplacePluginSchema),
-});
-
-type MarketplaceConfig = z.infer<typeof MarketplaceConfigSchema>;
-
-/** Parsed remote reference */
-export interface ParsedRemoteRef {
-  owner: string;
-  repo: string;
-  sha?: string;
-}
-
-/**
- * Normalize a GitHub URL to owner/repo format.
- * Returns null if the input is not a recognized GitHub URL.
- *
- * Supports:
- * - https://github.com/owner/repo
- * - https://github.com/owner/repo.git
- * - git@github.com:owner/repo.git
- */
-function normalizeGitHubUrl(input: string): string | null {
-  // HTTPS URL: https://github.com/owner/repo or https://github.com/owner/repo.git
-  const httpsMatch = input.match(/^https?:\/\/github\.com\/([^/]+)\/([^/@]+?)(?:\.git)?$/);
-  if (httpsMatch) {
-    return `${httpsMatch[1]}/${httpsMatch[2]}`;
-  }
-
-  // SSH URL: git@github.com:owner/repo.git
-  const sshMatch = input.match(/^git@github\.com:([^/]+)\/([^/@]+?)(?:\.git)?$/);
-  if (sshMatch) {
-    return `${sshMatch[1]}/${sshMatch[2]}`;
-  }
-
-  return null;
-}
-
-/**
- * Parse a remote reference string into its components.
- * Supports formats:
- * - "owner/repo" or "owner/repo@sha"
- * - "https://github.com/owner/repo" or "https://github.com/owner/repo@sha"
- * - "https://github.com/owner/repo.git" or "https://github.com/owner/repo.git@sha"
- * - "git@github.com:owner/repo.git" or "git@github.com:owner/repo.git@sha"
- */
-export function parseRemoteRef(ref: string): ParsedRemoteRef {
-  let inputRef = ref;
-  let sha: string | undefined;
-
-  // Extract SHA suffix from the input before URL normalization.
-  // The SHA is always at the end, after a @ that follows the repo name.
-  // For git@github.com URLs, we need to find the @ after the colon.
-  if (ref.startsWith('git@')) {
-    const colonIndex = ref.indexOf(':');
-    if (colonIndex !== -1) {
-      const afterColon = ref.slice(colonIndex + 1);
-      const shaAtIndex = afterColon.lastIndexOf('@');
-      if (shaAtIndex !== -1) {
-        sha = afterColon.slice(shaAtIndex + 1);
-        inputRef = ref.slice(0, colonIndex + 1 + shaAtIndex);
-      }
-    }
-  } else {
-    const lastAtIndex = ref.lastIndexOf('@');
-    if (lastAtIndex !== -1) {
-      const potentialSha = ref.slice(lastAtIndex + 1);
-      // SHA should not contain : or / (those would indicate URL structure)
-      if (!potentialSha.includes(':') && !potentialSha.includes('/')) {
-        if (!potentialSha) {
-          throw new SkillLoaderError(`Invalid remote ref: ${ref} (empty SHA after @)`);
-        }
-        sha = potentialSha;
-        inputRef = ref.slice(0, lastAtIndex);
-      }
-    }
-  }
-
-  // Normalize GitHub URLs to owner/repo format
-  const repoPath = normalizeGitHubUrl(inputRef) ?? inputRef;
-
-  const slashIndex = repoPath.indexOf('/');
-  if (slashIndex === -1) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (expected owner/repo format)`);
-  }
-
-  const owner = repoPath.slice(0, slashIndex);
-  const repo = repoPath.slice(slashIndex + 1);
-
-  if (!owner || !repo) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (empty owner or repo)`);
-  }
-
-  if (repo.includes('/')) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (repo name cannot contain /)`);
-  }
-
-  // Security: Prevent git flag injection by rejecting values starting with '-'
-  if (owner.startsWith('-')) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (owner cannot start with -)`);
-  }
-  if (repo.startsWith('-')) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (repo cannot start with -)`);
-  }
-  if (sha?.startsWith('-')) {
-    throw new SkillLoaderError(`Invalid remote ref: ${ref} (SHA cannot start with -)`);
-  }
-
-  return { owner, repo, sha };
-}
-
-/**
- * Format a parsed remote ref back to string format.
- */
-export function formatRemoteRef(parsed: ParsedRemoteRef): string {
-  const base = `${parsed.owner}/${parsed.repo}`;
-  return parsed.sha ? `${base}@${parsed.sha}` : base;
-}
-
-/**
- * Get the base directory for caching remote skills.
- * Respects WARDEN_STATE_DIR environment variable.
- * Default: ~/.local/warden/skills/
- */
-export function getSkillsCacheDir(): string {
-  const stateDir = process.env['WARDEN_STATE_DIR'];
-  if (stateDir) {
-    return join(stateDir, 'skills');
-  }
-  return join(homedir(), '.local', 'warden', 'skills');
-}
-
-/**
- * Get the cache path for a specific remote ref.
- * - Unpinned: ~/.local/warden/skills/owner/repo/
- * - Pinned: ~/.local/warden/skills/owner/repo@sha/
- */
-export function getRemotePath(ref: string): string {
-  const parsed = parseRemoteRef(ref);
-  const cacheDir = getSkillsCacheDir();
-
-  if (parsed.sha) {
-    return join(cacheDir, parsed.owner, `${parsed.repo}@${parsed.sha}`);
-  }
-  return join(cacheDir, parsed.owner, parsed.repo);
-}
-
-/**
- * Get the path to the state.json file.
- */
-export function getStatePath(): string {
-  return join(getSkillsCacheDir(), 'state.json');
-}
-
-/**
- * Load the remote state from state.json.
- * Returns an empty state if the file doesn't exist.
- */
-export function loadState(): RemoteState {
-  const statePath = getStatePath();
-
-  if (!existsSync(statePath)) {
-    return { remotes: {} };
-  }
-
-  try {
-    const content = readFileSync(statePath, 'utf-8');
-    const data = JSON.parse(content);
-    return RemoteStateSchema.parse(data);
-  } catch (error) {
-    // If state is corrupted, start fresh
-    const message = error instanceof Error ? error.message : String(error);
-    console.warn(`Warning: Failed to load state.json, starting fresh: ${message}`);
-    return { remotes: {} };
-  }
-}
-
-/**
- * Save the remote state to state.json.
- * Uses atomic write (write to temp, then rename).
- */
-export function saveState(state: RemoteState): void {
-  const statePath = getStatePath();
-  const stateDir = dirname(statePath);
-
-  // Ensure directory exists
-  if (!existsSync(stateDir)) {
-    mkdirSync(stateDir, { recursive: true });
-  }
-
-  // Write atomically
-  const tempPath = `${statePath}.tmp`;
-  writeFileSync(tempPath, JSON.stringify(state, null, 2), 'utf-8');
-
-  // Rename is atomic on most filesystems
-  renameSync(tempPath, statePath);
-}
-
-/**
- * Get the TTL for remote skill cache in seconds.
- * Respects WARDEN_SKILL_CACHE_TTL environment variable.
- */
-export function getCacheTtlSeconds(): number {
-  const envTtl = process.env['WARDEN_SKILL_CACHE_TTL'];
-  if (envTtl) {
-    const parsed = parseInt(envTtl, 10);
-    if (!isNaN(parsed) && parsed > 0) {
-      return parsed;
-    }
-  }
-  return DEFAULT_TTL_SECONDS;
-}
-
-/**
- * Check if an unpinned remote ref needs to be refreshed.
- * Pinned refs (with @sha) never need refresh.
- */
-export function shouldRefresh(ref: string, state: RemoteState): boolean {
-  const parsed = parseRemoteRef(ref);
-
-  // Pinned refs are immutable - never refresh
-  if (parsed.sha) {
-    return false;
-  }
-
-  const entry = state.remotes[ref];
-  if (!entry) {
-    return true; // Not cached, needs fetch
-  }
-
-  const fetchedAt = new Date(entry.fetchedAt).getTime();
-  const now = Date.now();
-  const ttl = getCacheTtlSeconds() * 1000;
-
-  return now - fetchedAt > ttl;
-}
-
-export interface FetchRemoteOptions {
-  /** Force refresh even if cache is valid */
-  force?: boolean;
-  /** Skip network operations - only use cache */
-  offline?: boolean;
-  /** Callback for progress messages */
-  onProgress?: (message: string) => void;
-}
-
-/**
- * Execute a git command and return stdout.
- * Uses execFileSync to avoid shell injection vulnerabilities.
- * Throws SkillLoaderError on failure.
- */
-function execGit(args: string[], options?: { cwd?: string }): string {
-  try {
-    return execFileSync('git', args, {
-      encoding: 'utf-8',
-      cwd: options?.cwd,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new SkillLoaderError(`Git command failed: git ${args.join(' ')}: ${message}`);
-  }
-}
-
-/**
- * Clone or update a remote repository to the cache.
- * Returns the SHA of the fetched commit.
- */
-export async function fetchRemote(ref: string, options: FetchRemoteOptions = {}): Promise<string> {
-  const { force = false, offline = false, onProgress } = options;
-  const parsed = parseRemoteRef(ref);
-  const remotePath = getRemotePath(ref);
-  const state = loadState();
-
-  const isPinned = !!parsed.sha;
-  const isCached = existsSync(remotePath);
-  const needsRefresh = shouldRefresh(ref, state);
-
-  // Check if we have a valid cache (directory exists AND state entry exists)
-  const stateEntry = state.remotes[ref];
-  const hasValidCache = isCached && !!stateEntry;
-
-  // Handle offline mode
-  if (offline) {
-    if (hasValidCache) {
-      return stateEntry.sha;
-    }
-    throw new SkillLoaderError(`Remote skill not cached and offline mode enabled: ${ref}`);
-  }
-
-  // Pinned + valid cache = use cache (SHA is immutable)
-  if (isPinned && hasValidCache && !force && parsed.sha) {
-    return parsed.sha;
-  }
-
-  // Unpinned + valid cache + fresh = use cache
-  if (!isPinned && hasValidCache && !needsRefresh && !force) {
-    return stateEntry.sha;
-  }
-
-  const repoUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
-
-  // Clone or update
-  if (!isCached) {
-    onProgress?.(`Cloning ${ref}...`);
-
-    // Ensure parent directory exists
-    const parentDir = dirname(remotePath);
-    if (!existsSync(parentDir)) {
-      mkdirSync(parentDir, { recursive: true });
-    }
-
-    // Clone with minimal depth for unpinned refs
-    // Note: '--' separates flags from positional args to prevent flag injection
-    if (isPinned && parsed.sha) {
-      // For pinned refs, we need full history to checkout the specific SHA
-      // Use a shallow clone then deepen if needed
-      execGit(['clone', '--depth=1', '--', repoUrl, remotePath]);
-
-      try {
-        // Try to checkout the pinned SHA
-        // Note: 'checkout' without '--' treats arg as ref; with '--' it's a file path
-        execGit(['fetch', '--depth=1', 'origin', '--', parsed.sha], { cwd: remotePath });
-        execGit(['checkout', parsed.sha], { cwd: remotePath });
-      } catch {
-        // If SHA not found, do a full fetch and retry
-        execGit(['fetch', '--unshallow'], { cwd: remotePath });
-        execGit(['checkout', parsed.sha], { cwd: remotePath });
-      }
-    } else if (!isPinned) {
-      // For unpinned refs, shallow clone of default branch
-      execGit(['clone', '--depth=1', '--', repoUrl, remotePath]);
-    }
-  } else {
-    // Update existing cache
-    onProgress?.(`Updating ${ref}...`);
-
-    if (!isPinned) {
-      // For unpinned refs, pull latest
-      execGit(['fetch', '--depth=1', 'origin'], { cwd: remotePath });
-      execGit(['reset', '--hard', 'origin/HEAD'], { cwd: remotePath });
-    }
-    // Pinned refs don't need updates - SHA is immutable
-  }
-
-  // Get the current HEAD SHA
-  const sha = execGit(['rev-parse', 'HEAD'], { cwd: remotePath });
-
-  // Update state
-  state.remotes[ref] = {
-    sha,
-    fetchedAt: new Date().toISOString(),
-  };
-  saveState(state);
-
-  return sha;
-}
-
-export interface DiscoveredRemoteSkill {
-  name: string;
-  description: string;
-  path: string;
-  /** Plugin name for marketplace format skills */
-  pluginName?: string;
-}
-
-/**
- * Parse marketplace.json from a remote repository if it exists.
- * Returns null if the file doesn't exist or is invalid.
- */
-function parseMarketplaceConfig(remotePath: string): MarketplaceConfig | null {
-  const marketplacePath = join(remotePath, '.claude-plugin', 'marketplace.json');
-
-  if (!existsSync(marketplacePath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(marketplacePath, 'utf-8');
-    const data = JSON.parse(content);
-    return MarketplaceConfigSchema.parse(data);
-  } catch {
-    // Invalid or malformed marketplace.json - fall back to traditional discovery
-    return null;
-  }
-}
-
-/** Directories to search for skills in remote repositories */
-const REMOTE_SKILL_DIRECTORIES = [
-  '',               // root level
-  'skills',         // skills/ subdirectory
-  '.warden/skills', // Warden-specific
-  '.agents/skills', // General agent skills
-  '.claude/skills', // Claude Code skills
-];
-
-/**
- * Discover skills using traditional directory layout.
- * Searches root level, skills/, and conventional skill directories.
- */
-async function discoverTraditionalSkills(remotePath: string): Promise<DiscoveredRemoteSkill[]> {
-  const skills: DiscoveredRemoteSkill[] = [];
-  const seenNames = new Set<string>();
-
-  for (const subdir of REMOTE_SKILL_DIRECTORIES) {
-    const searchPath = subdir ? join(remotePath, subdir) : remotePath;
-    if (!existsSync(searchPath)) continue;
-
-    const entries = readdirSync(searchPath);
-
-    for (const entry of entries) {
-      if (entry.startsWith('.')) continue;
-
-      const entryPath = join(searchPath, entry);
-      const stat = statSync(entryPath);
-
-      if (stat.isDirectory()) {
-        const skillMdPath = join(entryPath, 'SKILL.md');
-        if (existsSync(skillMdPath)) {
-          try {
-            const skill = await loadSkillFromMarkdown(skillMdPath);
-            // First occurrence wins (root takes precedence over skills/)
-            if (!seenNames.has(skill.name)) {
-              seenNames.add(skill.name);
-              skills.push({
-                name: skill.name,
-                description: skill.description,
-                path: entryPath,
-              });
-            }
-          } catch {
-            // Skip invalid skill directories
-          }
-        }
-      }
-    }
-  }
-
-  return skills;
-}
-
-/**
- * Discover skills using marketplace format.
- * Searches plugins/{plugin}/skills/ for each plugin defined in marketplace.json.
- */
-async function discoverMarketplaceSkills(
-  remotePath: string,
-  config: MarketplaceConfig
-): Promise<DiscoveredRemoteSkill[]> {
-  const skills: DiscoveredRemoteSkill[] = [];
-  const seenNames = new Set<string>();
-
-  for (const plugin of config.plugins) {
-    // Resolve plugin source path (e.g., "./plugins/sentry-skills" -> "plugins/sentry-skills")
-    const pluginSource = plugin.source.replace(/^\.\//, '');
-    const skillsPath = join(remotePath, pluginSource, 'skills');
-
-    if (!existsSync(skillsPath)) continue;
-
-    const entries = readdirSync(skillsPath);
-
-    for (const entry of entries) {
-      if (entry.startsWith('.')) continue;
-
-      const entryPath = join(skillsPath, entry);
-      const stat = statSync(entryPath);
-
-      if (stat.isDirectory()) {
-        const skillMdPath = join(entryPath, 'SKILL.md');
-        if (existsSync(skillMdPath)) {
-          try {
-            const skill = await loadSkillFromMarkdown(skillMdPath);
-            // First plugin wins for duplicate skill names
-            if (!seenNames.has(skill.name)) {
-              seenNames.add(skill.name);
-              skills.push({
-                name: skill.name,
-                description: skill.description,
-                path: entryPath,
-                pluginName: plugin.name,
-              });
-            }
-          } catch {
-            // Skip invalid skill directories
-          }
-        }
-      }
-    }
-  }
-
-  return skills;
-}
-
-/**
- * Discover all skills in a cached remote repository.
- * Detects format and delegates to appropriate discovery function:
- * - If .claude-plugin/marketplace.json exists, uses marketplace discovery
- * - Otherwise, uses traditional discovery (root, skills/, .warden/skills, etc.)
- */
-export async function discoverRemoteSkills(ref: string): Promise<DiscoveredRemoteSkill[]> {
-  const remotePath = getRemotePath(ref);
-
-  if (!existsSync(remotePath)) {
-    throw new SkillLoaderError(`Remote not cached: ${ref}. Run fetch first.`);
-  }
-
-  // Check for marketplace format
-  const marketplaceConfig = parseMarketplaceConfig(remotePath);
-  if (marketplaceConfig) {
-    return discoverMarketplaceSkills(remotePath, marketplaceConfig);
-  }
-
-  // Fall back to traditional discovery
-  return discoverTraditionalSkills(remotePath);
-}
-
-/**
- * Resolve a skill from a remote repository.
- * Ensures the remote is fetched/cached, then loads the skill.
- * Matches by skill name (from SKILL.md), not directory name.
- */
-export async function resolveRemoteSkill(
-  ref: string,
-  skillName: string,
-  options: FetchRemoteOptions = {}
-): Promise<SkillDefinition> {
-  await fetchRemote(ref, options);
-
-  const availableSkills = await discoverRemoteSkills(ref);
-  const match = availableSkills.find((s) => s.name === skillName);
-
-  if (match) {
-    return loadSkillFromMarkdown(join(match.path, 'SKILL.md'));
-  }
-
-  if (availableSkills.length === 0) {
-    throw new SkillLoaderError(`No skills found in remote: ${ref}`);
-  }
-
-  throw new SkillLoaderError(
-    `Skill '${skillName}' not found in remote: ${ref}. Available skills: ${availableSkills.map((s) => s.name).join(', ')}`
-  );
-}
-
-/**
- * Remove a remote from the cache.
- */
-export function removeRemote(ref: string): void {
-  const remotePath = getRemotePath(ref);
-
-  if (existsSync(remotePath)) {
-    rmSync(remotePath, { recursive: true, force: true });
-  }
-
-  const state = loadState();
-  const { [ref]: _removed, ...remainingRemotes } = state.remotes;
-  state.remotes = remainingRemotes;
-  saveState(state);
-}
-
-/**
- * List all cached remotes with their metadata.
- */
-export function listCachedRemotes(): { ref: string; entry: RemoteEntry }[] {
-  const state = loadState();
-  return Object.entries(state.remotes).map(([ref, entry]) => ({ ref, entry }));
-}