craftdesk 0.1.0 → 0.3.0

package/src/services/git-resolver.ts

@@ -0,0 +1,373 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { execSync } from 'child_process';
+import { logger } from '../utils/logger';
+import { CraftDeskJson, DependencyConfig } from '../types/craftdesk-json';
+
+/**
+ * Information about a git dependency
+ */
+export interface GitDependencyInfo {
+  /** Git repository URL */
+  url: string;
+  /** Optional branch name */
+  branch?: string;
+  /** Optional tag name */
+  tag?: string;
+  /** Optional commit hash */
+  commit?: string;
+  /** Optional subdirectory path for monorepos */
+  path?: string;
+  /** Optional direct file path (e.g., skill.md, agent.md) */
+  file?: string;
+  /** Parsed craftdesk.json from the repository */
+  craftDeskJson?: CraftDeskJson;
+  /** Resolved full commit hash */
+  resolvedCommit?: string;
+}
+
+/**
+ * Resolves git dependencies and extracts their metadata
+ *
+ * Handles cloning git repositories, reading craftdesk.json, inferring craft types
+ * when metadata is missing, and supporting monorepo structures with subdirectory paths.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new GitResolver();
+ *
+ * // Resolve a git dependency
+ * const info = await resolver.resolveGitDependency({
+ *   url: 'https://github.com/company/auth.git',
+ *   branch: 'main'
+ * });
+ *
+ * console.log(info.craftDeskJson.name); // 'auth-skill'
+ * console.log(info.resolvedCommit); // Full commit hash
+ * ```
+ */
+export class GitResolver {
+  private tempDir: string;
+
+  constructor() {
+    this.tempDir = path.join(process.cwd(), '.craftdesk', 'tmp');
+  }
+
+  /**
+   * Resolves a git dependency by cloning and reading its craftdesk.json
+   *
+   * Process:
+   * 1. Clones the repository (shallow clone for efficiency)
+   * 2. Checks out specified branch/tag/commit
+   * 3. Reads craftdesk.json from repository, subdirectory, or infers from direct file
+   * 4. Generates minimal metadata if craftdesk.json is missing
+   * 5. Infers craft type from marker files, direct file extension, or directory structure
+   *
+   * @param gitInfo - Git dependency information
+   * @returns Enhanced git info with craftdesk.json and resolved commit
+   *
+   * @example
+   * ```typescript
+   * // With craftdesk.json in repository
+   * const info = await resolver.resolveGitDependency({
+   *   url: 'https://github.com/user/skill.git',
+   *   tag: 'v1.0.0'
+   * });
+   *
+   * // Monorepo with subdirectory
+   * const info = await resolver.resolveGitDependency({
+   *   url: 'https://github.com/company/monorepo.git',
+   *   tag: 'v3.0.0',
+   *   path: 'crafts/auth'
+   * });
+   *
+   * // Direct file reference
+   * const info = await resolver.resolveGitDependency({
+   *   url: 'https://github.com/user/repo.git',
+   *   branch: 'main',
+   *   file: 'rspec-dry-agent.md'
+   * });
+   * ```
+   */
+  async resolveGitDependency(gitInfo: GitDependencyInfo): Promise<GitDependencyInfo> {
+    const repoTempDir = path.join(this.tempDir, `git-${Date.now()}`);
+
+    try {
+      await fs.ensureDir(repoTempDir);
+
+      // Clone the repository
+      logger.debug(`Cloning ${gitInfo.url} to analyze dependencies...`);
+
+      let cloneCmd = `git clone --depth 1`;
+      if (gitInfo.branch) {
+        cloneCmd += ` -b ${gitInfo.branch}`;
+      } else if (gitInfo.tag) {
+        cloneCmd += ` -b ${gitInfo.tag}`;
+      }
+      cloneCmd += ` ${gitInfo.url} ${repoTempDir}`;
+
+      execSync(cloneCmd, { stdio: 'pipe' });
+
+      // If specific commit, checkout that commit
+      if (gitInfo.commit) {
+        execSync(`cd ${repoTempDir} && git fetch --unshallow && git checkout ${gitInfo.commit}`, { stdio: 'pipe' });
+      }
+
+      // Get the actual commit hash for lockfile
+      const resolvedCommit = execSync(`cd ${repoTempDir} && git rev-parse HEAD`, { encoding: 'utf8' }).trim();
+      gitInfo.resolvedCommit = resolvedCommit;
+
+      // Handle direct file reference
+      if (gitInfo.file) {
+        const filePath = path.join(repoTempDir, gitInfo.file);
+
+        if (await fs.pathExists(filePath)) {
+          logger.debug(`Found direct file reference: ${gitInfo.file}`);
+
+          // Try to find craftdesk.json to get type and metadata
+          let craftType: 'skill' | 'agent' | 'command' | 'hook' | 'plugin' | undefined;
+          let craftName: string | undefined;
+          let craftVersion: string | undefined;
+          let craftDeps: Record<string, any> | undefined;
+
+          // Check for craftdesk.json in same directory as file
+          const fileDir = path.dirname(gitInfo.file);
+          const fileDirCraftPath = path.join(repoTempDir, fileDir, 'craftdesk.json');
+
+          // Check for craftdesk.json in repo root
+          const rootCraftPath = path.join(repoTempDir, 'craftdesk.json');
+
+          if (await fs.pathExists(fileDirCraftPath)) {
+            const content = await fs.readFile(fileDirCraftPath, 'utf-8');
+            const craftJson = JSON.parse(content);
+            logger.debug(`Found craftdesk.json in file directory: ${craftJson.name}@${craftJson.version}`);
+            craftType = craftJson.type;
+            craftName = craftJson.name;
+            craftVersion = craftJson.version;
+            craftDeps = craftJson.dependencies;
+          } else if (await fs.pathExists(rootCraftPath)) {
+            const content = await fs.readFile(rootCraftPath, 'utf-8');
+            const craftJson = JSON.parse(content);
+            logger.debug(`Found craftdesk.json in repo root: ${craftJson.name}@${craftJson.version}`);
+            craftType = craftJson.type;
+            craftName = craftJson.name;
+            craftVersion = craftJson.version;
+            craftDeps = craftJson.dependencies;
+          }
+
+          // If no craftdesk.json found, infer from filename
+          if (!craftType) {
+            craftType = this.inferCraftTypeFromFilename(gitInfo.file);
+          }
+
+          // Create minimal craftdesk.json from file
+          gitInfo.craftDeskJson = {
+            name: craftName || path.basename(gitInfo.file, path.extname(gitInfo.file)),
+            version: craftVersion || gitInfo.tag || gitInfo.branch || resolvedCommit.substring(0, 7),
+            type: craftType,
+            description: `Git file dependency from ${gitInfo.url}/${gitInfo.file}`,
+            dependencies: craftDeps || {}
+          };
+        } else {
+          throw new Error(`File not found: ${gitInfo.file} in ${gitInfo.url}`);
+        }
+      } else {
+        // Look for craftdesk.json in the specified path or root
+        const craftPath = gitInfo.path
+          ? path.join(repoTempDir, gitInfo.path, 'craftdesk.json')
+          : path.join(repoTempDir, 'craftdesk.json');
+
+        if (await fs.pathExists(craftPath)) {
+          const content = await fs.readFile(craftPath, 'utf-8');
+          gitInfo.craftDeskJson = JSON.parse(content);
+          logger.debug(`Found craftdesk.json in git repository: ${gitInfo.craftDeskJson!.name}@${gitInfo.craftDeskJson!.version}`);
+        } else {
+          // No craftdesk.json found - create a minimal one
+          logger.warn(`No craftdesk.json found in ${gitInfo.url}${gitInfo.path ? `#path:${gitInfo.path}` : ''}`);
+
+          // Try to infer the type from directory structure
+          const type = await this.inferCraftType(repoTempDir, gitInfo.path);
+
+          gitInfo.craftDeskJson = {
+            name: path.basename(gitInfo.url, '.git'),
+            version: gitInfo.tag || gitInfo.branch || resolvedCommit.substring(0, 7),
+            type: type,
+            description: `Git dependency from ${gitInfo.url}`,
+            dependencies: {}
+          };
+        }
+      }
+
+      return gitInfo;
+
+    } finally {
+      // Clean up temp directory
+      await fs.remove(repoTempDir);
+    }
+  }
+
+  /**
+   * Infers the craft type from a filename
+   *
+   * Type inference strategy:
+   * 1. Check filename for type indicators: agent, skill, command, hook
+   * 2. Check file extension patterns
+   * 3. Default to 'skill' if no indicators found
+   *
+   * @param filename - The filename to analyze
+   * @returns The inferred craft type
+   * @private
+   */
+  private inferCraftTypeFromFilename(filename: string): 'skill' | 'agent' | 'command' | 'hook' | 'plugin' {
+    const lower = filename.toLowerCase();
+
+    // Check filename for type indicators
+    if (lower.includes('agent')) return 'agent';
+    if (lower.includes('command')) return 'command';
+    if (lower.includes('hook')) return 'hook';
+    if (lower.includes('plugin')) return 'plugin';
+    if (lower.includes('skill')) return 'skill';
+
+    // Default to skill
+    return 'skill';
+  }
+
+  /**
+   * Infers the craft type from the repository structure
+   *
+   * Type inference strategy:
+   * 1. Check for marker files: SKILL.md, AGENT.md, COMMAND.md, HOOK.md
+   * 2. Check directory name for type indicators
+   * 3. Default to 'skill' if no indicators found
+   *
+   * @param repoPath - Path to the cloned repository
+   * @param subPath - Optional subdirectory to check
+   * @returns The inferred craft type
+   * @private
+   */
+  private async inferCraftType(repoPath: string, subPath?: string): Promise<'skill' | 'agent' | 'command' | 'hook' | 'plugin'> {
+    const checkPath = subPath ? path.join(repoPath, subPath) : repoPath;
+
+    // Check for type-indicating files
+    const files = await fs.readdir(checkPath);
+
+    // Look for SKILL.md, AGENT.md, COMMAND.md, HOOK.md, PLUGIN.md
+    if (files.includes('SKILL.md')) return 'skill';
+    if (files.includes('AGENT.md')) return 'agent';
+    if (files.includes('COMMAND.md')) return 'command';
+    if (files.includes('HOOK.md')) return 'hook';
+    if (files.includes('PLUGIN.md')) return 'plugin';
+
+    // Check directory name hints
+    const dirName = subPath ? path.basename(subPath) : path.basename(repoPath);
+    if (dirName.includes('skill')) return 'skill';
+    if (dirName.includes('agent')) return 'agent';
+    if (dirName.includes('command')) return 'command';
+    if (dirName.includes('hook')) return 'hook';
+    if (dirName.includes('plugin')) return 'plugin';
+
+    // Default to skill
+    return 'skill';
+  }
+
+  /**
+   * Resolves all dependencies including transitive dependencies from git sources
+   *
+   * Uses a breadth-first traversal algorithm to resolve dependencies recursively.
+   * Tracks visited packages to avoid circular dependencies.
+   *
+   * @param dependencies - Map of dependency names to version strings or config objects
+   * @returns Object containing resolved dependencies and generated lockfile
+   *
+   * @example
+   * ```typescript
+   * const result = await resolver.resolveAllDependencies({
+   *   'ruby-on-rails': '^7.0.0',
+   *   'custom-auth': {
+   *     git: 'https://github.com/company/auth.git',
+   *     branch: 'main'
+   *   }
+   * });
+   *
+   * console.log(result.resolved); // All dependencies including transitive
+   * console.log(result.lockfile); // Generated lockfile structure
+   * ```
+   */
+  async resolveAllDependencies(dependencies: Record<string, string | DependencyConfig>): Promise<{
+    resolved: Record<string, any>;
+    lockfile: any;
+  }> {
+    const resolved: Record<string, any> = {};
+    // Queue of dependencies to resolve (breadth-first traversal)
+    const toResolve: Array<[string, string | DependencyConfig]> = Object.entries(dependencies);
+    // Track visited packages to prevent infinite loops from circular dependencies
+    const visited = new Set<string>();
+
+    // Process queue until all dependencies are resolved
+    while (toResolve.length > 0) {
+      const [name, dep] = toResolve.shift()!;
+
+      // Skip if already resolved (handles duplicates and circular deps)
+      if (visited.has(name)) continue;
+      visited.add(name);
+
+      // Determine if this is a git or registry dependency
+      if (typeof dep === 'object' && dep.git) {
+        // Git dependency - clone repository and extract metadata
+        const gitInfo = await this.resolveGitDependency({
+          url: dep.git,
+          branch: dep.branch,
+          tag: dep.tag,
+          commit: dep.commit,
+          path: dep.path,
+          file: dep.file
+        });
+
+        resolved[name] = {
+          version: gitInfo.craftDeskJson?.version || '0.0.0',
+          resolved: gitInfo.url,
+          integrity: gitInfo.resolvedCommit || 'git',
+          type: gitInfo.craftDeskJson?.type || 'skill',
+          author: gitInfo.craftDeskJson?.author || 'git',
+          git: gitInfo.url,
+          ...(gitInfo.branch && { branch: gitInfo.branch }),
+          ...(gitInfo.tag && { tag: gitInfo.tag }),
+          ...(gitInfo.commit && { commit: gitInfo.resolvedCommit }),
+          ...(gitInfo.path && { path: gitInfo.path }),
+          ...(gitInfo.file && { file: gitInfo.file }),
+          dependencies: gitInfo.craftDeskJson?.dependencies || {}
+        };
+
+        // Add transitive dependencies to the resolution queue
+        // This enables recursive dependency resolution
+        if (gitInfo.craftDeskJson?.dependencies) {
+          for (const [depName, depVersion] of Object.entries(gitInfo.craftDeskJson.dependencies)) {
+            // Only add if not already visited (avoids redundant resolution)
+            if (!visited.has(depName)) {
+              toResolve.push([depName, depVersion]);
+            }
+          }
+        }
+      } else {
+        // Registry dependency - mark for resolution by registry client
+        // The actual version resolution happens via the registry API
+        resolved[name] = {
+          needsResolution: true,
+          version: typeof dep === 'string' ? dep : dep.version,
+          registry: typeof dep === 'object' ? dep.registry : undefined
+        };
+      }
+    }
+
+    return {
+      resolved,
+      lockfile: {
+        version: '1.0.0',
+        lockfileVersion: 1,
+        crafts: resolved
+      }
+    };
+  }
+}
+
+export const gitResolver = new GitResolver();

package/src/services/installer.ts

@@ -0,0 +1,314 @@
+import path from 'path';
+import fs from 'fs-extra';
+import axios from 'axios';
+import { logger } from '../utils/logger';
+import { configManager } from './config-manager';
+import { CraftDeskLock, LockEntry } from '../types/craftdesk-lock';
+import { ensureDir } from '../utils/file-system';
+
+/**
+ * Handles installation of crafts from various sources
+ *
+ * Supports installing from:
+ * - Registry packages (via download URLs)
+ * - Git repositories (with monorepo support)
+ * - Local archives
+ *
+ * Organizes installations by craft type in the .claude directory.
+ *
+ * @example
+ * ```typescript
+ * const installer = new Installer();
+ *
+ * // Install from lockfile
+ * const lockfile = await readLockfile();
+ * await installer.installFromLockfile(lockfile);
+ *
+ * // Install single craft
+ * await installer.installCraft('ruby-on-rails', lockEntry);
+ * ```
+ */
+export class Installer {
+  private installPath: string;
+
+  constructor() {
+    this.installPath = configManager.getInstallPath();
+  }
+
+  /**
+   * Installs all crafts defined in a lockfile
+   *
+   * Processes each craft sequentially, updating progress as it goes.
+   * Fails fast if any installation errors occur.
+   *
+   * @param lockfile - The craftdesk.lock content with all dependencies
+   * @throws Error if any craft fails to install
+   *
+   * @example
+   * ```typescript
+   * const lockfile = {
+   *   version: '1.0.0',
+   *   lockfileVersion: 1,
+   *   crafts: {
+   *     'ruby-on-rails': { version: '7.1.0', ... },
+   *     'postgres-expert': { version: '1.2.0', ... }
+   *   }
+   * };
+   *
+   * await installer.installFromLockfile(lockfile);
+   * ```
+   */
+  async installFromLockfile(lockfile: CraftDeskLock): Promise<void> {
+    const installDir = path.join(process.cwd(), this.installPath);
+    await ensureDir(installDir);
+
+    const crafts = Object.entries(lockfile.crafts);
+    let installed = 0;
+
+    for (const [name, entry] of crafts) {
+      try {
+        logger.updateSpinner(`Installing ${name}@${entry.version} (${installed + 1}/${crafts.length})`);
+        await this.installCraft(name, entry);
+        installed++;
+      } catch (error: any) {
+        logger.failSpinner(`Failed to install ${name}: ${error.message}`);
+        throw error;
+      }
+    }
+
+    logger.succeedSpinner(`Installed ${installed} crafts`);
+  }
+
+  /**
+   * Installs a single craft from registry or git source
+   *
+   * Installation process:
+   * 1. Determines installation directory based on craft type
+   * 2. For git dependencies: clones and extracts subdirectory
+   * 3. For registry: downloads archive, verifies, and extracts
+   * 4. Creates metadata file for tracking installation
+   *
+   * @param name - The name of the craft to install
+   * @param entry - Lockfile entry containing installation details
+   * @throws Error if download or extraction fails
+   *
+   * @example
+   * ```typescript
+   * // Install from registry
+   * await installer.installCraft('ruby-on-rails', {
+   *   version: '7.1.0',
+   *   resolved: 'https://craftdesk.ai/download/...',
+   *   type: 'skill',
+   *   dependencies: {}
+   * });
+   *
+   * // Install from git
+   * await installer.installCraft('custom-auth', {
+   *   version: '1.0.0',
+   *   git: 'https://github.com/company/auth.git',
+   *   branch: 'main',
+   *   type: 'agent',
+   *   dependencies: {}
+   * });
+   * ```
+   */
+  async installCraft(name: string, entry: LockEntry): Promise<void> {
+    const installDir = path.join(process.cwd(), this.installPath);
+
+    // Determine install subdirectory based on type
+    const typeDir = this.getTypeDirectory(entry.type);
+    const craftDir = path.join(installDir, typeDir, name);
+
+    // Create directory
+    await ensureDir(craftDir);
+
+    // Check if this is a git dependency
+    if (entry.git) {
+      await this.installFromGit(craftDir, entry);
+    } else {
+      // Download craft archive
+      const archivePath = path.join(craftDir, 'archive.tar.gz');
+      await this.downloadFile(entry.resolved, archivePath);
+
+      // Verify integrity (TODO: implement SHA-256 check)
+      // await this.verifyIntegrity(archivePath, entry.integrity);
+
+      // Extract archive
+      await this.extractArchive(archivePath, craftDir);
+
+      // Clean up archive
+      await fs.remove(archivePath);
+    }
+
+    // Create metadata file
+    await this.createMetadata(craftDir, name, entry);
+  }
+
+  private async installFromGit(craftDir: string, entry: LockEntry): Promise<void> {
+    const tempDir = path.join(craftDir, '.tmp-git');
+
+    try {
+      // Clone the repository
+      const { execSync } = require('child_process');
+
+      // Build clone command with appropriate ref
+      let cloneCmd = `git clone --depth 1`;
+
+      if (entry.branch) {
+        cloneCmd += ` -b ${entry.branch}`;
+      } else if (entry.tag) {
+        cloneCmd += ` -b ${entry.tag}`;
+      }
+
+      cloneCmd += ` ${entry.git} ${tempDir}`;
+
+      logger.debug(`Cloning git repository: ${cloneCmd}`);
+      execSync(cloneCmd, { stdio: 'pipe' });
+
+      // If specific commit, checkout that commit
+      if (entry.commit) {
+        execSync(`cd ${tempDir} && git fetch --unshallow && git checkout ${entry.commit}`, { stdio: 'pipe' });
+      }
+
+      // Handle direct file reference
+      if (entry.file) {
+        const sourceFile = path.join(tempDir, entry.file);
+        const destFile = path.join(craftDir, path.basename(entry.file));
+
+        if (await fs.pathExists(sourceFile)) {
+          await fs.copy(sourceFile, destFile, { overwrite: true });
+        } else {
+          throw new Error(`File not found: ${entry.file} in ${entry.git}`);
+        }
+      } else {
+        // Copy from subdirectory if specified, otherwise copy entire repo
+        const sourcePath = entry.path ? path.join(tempDir, entry.path) : tempDir;
+
+        // Copy contents to craft directory
+        const files = await fs.readdir(sourcePath);
+        for (const file of files) {
+          if (file !== '.tmp-git' && file !== '.git') {
+            await fs.copy(
+              path.join(sourcePath, file),
+              path.join(craftDir, file),
+              { overwrite: true }
+            );
+          }
+        }
+      }
+
+    } finally {
+      // Clean up temp directory
+      await fs.remove(tempDir);
+    }
+  }
+
+  private getTypeDirectory(type: string): string {
+    switch (type) {
+      case 'skill':
+        return 'skills';
+      case 'agent':
+        return 'agents';
+      case 'command':
+        return 'commands';
+      case 'hook':
+        return 'hooks';
+      default:
+        return 'crafts';
+    }
+  }
+
+  private async downloadFile(url: string, outputPath: string): Promise<void> {
+    const response = await axios({
+      method: 'GET',
+      url: url,
+      responseType: 'stream'
+    });
+
+    const writer = fs.createWriteStream(outputPath);
+    response.data.pipe(writer);
+
+    return new Promise((resolve, reject) => {
+      writer.on('finish', resolve);
+      writer.on('error', reject);
+    });
+  }
+
+  private async extractArchive(archivePath: string, outputDir: string): Promise<void> {
+    // For now, just copy some placeholder files
+    // In production, this would extract a tar.gz or zip archive
+
+    const type = path.basename(outputDir).includes('skill') ? 'SKILL' : 'AGENT';
+    const mainFile = `${type}.md`;
+
+    await fs.writeFile(
+      path.join(outputDir, mainFile),
+      `# ${path.basename(outputDir)}\n\nThis is a placeholder for the ${type.toLowerCase()} content.\n`,
+      'utf-8'
+    );
+  }
+
+  private async createMetadata(craftDir: string, name: string, entry: LockEntry): Promise<void> {
+    const metadata = {
+      name,
+      version: entry.version,
+      type: entry.type,
+      author: entry.author,
+      installedAt: new Date().toISOString(),
+      registry: entry.registry,
+      dependencies: entry.dependencies
+    };
+
+    await fs.writeFile(
+      path.join(craftDir, '.craftdesk-metadata.json'),
+      JSON.stringify(metadata, null, 2),
+      'utf-8'
+    );
+  }
+
+  async removeCraft(name: string, type: string): Promise<void> {
+    const installDir = path.join(process.cwd(), this.installPath);
+    const typeDir = this.getTypeDirectory(type);
+    const craftDir = path.join(installDir, typeDir, name);
+
+    if (await fs.pathExists(craftDir)) {
+      await fs.remove(craftDir);
+      logger.success(`Removed ${name}`);
+    } else {
+      logger.warn(`${name} is not installed`);
+    }
+  }
+
+  async listInstalled(): Promise<Array<{ name: string; version: string; type: string }>> {
+    const installDir = path.join(process.cwd(), this.installPath);
+    const installed: Array<{ name: string; version: string; type: string }> = [];
+
+    if (!await fs.pathExists(installDir)) {
+      return installed;
+    }
+
+    const typeDirs = ['skills', 'agents', 'commands', 'hooks', 'plugins'];
+
+    for (const typeDir of typeDirs) {
+      const dir = path.join(installDir, typeDir);
+      if (!await fs.pathExists(dir)) continue;
+
+      const crafts = await fs.readdir(dir);
+      for (const craftName of crafts) {
+        const metadataPath = path.join(dir, craftName, '.craftdesk-metadata.json');
+        if (await fs.pathExists(metadataPath)) {
+          const metadata = await fs.readJson(metadataPath);
+          installed.push({
+            name: craftName,
+            version: metadata.version,
+            type: metadata.type
+          });
+        }
+      }
+    }
+
+    return installed;
+  }
+}
+
+export const installer = new Installer();