itismyskillmarket 1.0.10

package/src/commands/install.ts

@@ -0,0 +1,237 @@
+/**
+ * =============================================================================
+ * SkillMarket 安装命令模块
+ * =============================================================================
+ * 
+ * 本模块实现 `skm install` 命令，用于安装 skill 到本地。
+ * 
+ * 安装流程:
+ * 1. 确保目录结构存在
+ * 2. 从 npm 获取包信息
+ * 3. 下载包到缓存
+ * 4. 解压并复制到 skills 目录
+ * 5. 创建 latest 软链接
+ * 6. 更新本地注册表
+ * 
+ * 安装后的目录结构:
+ * ~/.skillmarket/
+ * ├── skills/
+ * │   └── <skillId>/
+ * │       ├── latest -> <version>/  (软链接)
+ * │       └── <version>/
+ * │           ├── SKILL.md
+ * │           └── metadata.json
+ * └── ...
+ * 
+ * @module commands/install
+ */
+
+// -----------------------------------------------------------------------------
+// 导入依赖
+// -----------------------------------------------------------------------------
+
+import fs from 'fs-extra';          // 文件系统操作
+import path from 'path';             // 路径处理
+import { exec } from 'child_process'; // 执行 shell 命令
+import { promisify } from 'util';    // Promise 化工具
+
+// 模块导入
+import { fetchNpmPackage } from './npm.js';         // npm 查询
+import { loadRegistry, saveRegistry } from './registry.js';  // 注册表操作
+import { getCacheDir, getSkillsDir, ensureMarketDirs } from '../utils/dirs.js';  // 目录工具
+import { detectPlatform } from '../utils/platform.js';  // 平台检测
+import { LATEST_LINK } from '../constants.js';       // 常量
+import type { InstalledSkill } from '../types.js';    // 类型定义
+
+// 将 exec 转为 Promise 形式
+const execAsync = promisify(exec);
+
+// -----------------------------------------------------------------------------
+// 安装函数
+// -----------------------------------------------------------------------------
+
+/**
+ * 安装指定的 skill
+ * 
+ * @param {string} skillId - Skill 标识符（支持短格式或 scoped 格式）
+ * @param {string} [version] - 指定版本号（可选，不指定则安装最新版本）
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * // 安装最新版本的 brainstorming
+ * await installSkill('brainstorming');
+ * 
+ * // 安装指定版本
+ * await installSkill('brainstorming', '1.0.0');
+ * 
+ * // 安装 scoped 包
+ * await installSkill('@custom/skill');
+ */
+export async function installSkill(
+  skillId: string, 
+  version?: string
+): Promise<void> {
+  // ==========================================================================
+  // 步骤 0: 准备
+  // ==========================================================================
+  
+  // 确保所有必要的目录都已创建
+  await ensureMarketDirs();
+  
+  // 转换包名格式
+  // 支持 @itismyskillmarket/ 和 @skillmarket/ 两种 scope
+  let packageName: string;
+  if (skillId.startsWith('@')) {
+    // 直接使用用户提供的 scoped 包名
+    packageName = skillId;
+  } else {
+    // 默认尝试 @itismyskillmarket/，失败后回退到 @skillmarket/
+    packageName = `@itismyskillmarket/${skillId}`;
+  }
+  
+  console.log(`Installing ${packageName}${version ? `@${version}` : ''}...`);
+  
+  // ==========================================================================
+  // 步骤 1: 获取包信息
+  // ==========================================================================
+  
+  // 从 npm 查询包的元信息
+  const pkgInfo = await fetchNpmPackage(packageName);
+  if (!pkgInfo) {
+    throw new Error(`Package ${packageName} not found`);
+  }
+  
+  // 确定要安装的版本（用户指定版本 > 最新版本）
+  const targetVersion = version || pkgInfo['dist-tags']?.latest;
+  if (!targetVersion) {
+    throw new Error(`No version found for ${packageName}`);
+  }
+  
+  // ==========================================================================
+  // 步骤 2: 下载包到缓存
+  // ==========================================================================
+  
+  const cacheDir = getCacheDir();
+  
+  // 计算目标缓存目录路径
+  // 例如: ~/.skillmarket/cache/@skillmarket%2Fbrainstorming@1.0.0/
+  const targetDir = path.join(cacheDir, `${packageName}@${targetVersion}`);
+  
+  // 如果缓存已存在，跳过下载
+  if (!(await fs.pathExists(targetDir))) {
+    console.log('Downloading package...');
+    await fs.ensureDir(cacheDir);
+    
+    try {
+      // 使用 npm pack 下载包到指定目录
+      // npm pack 会生成 .tgz 文件
+      await execAsync(`npm pack ${packageName}@${targetVersion} --pack-destination ${cacheDir}`);
+      
+      // 查找下载的 tarball 文件
+      const files = await fs.readdir(cacheDir);
+      
+      // npm pack 生成的文件名格式: <package-name>-<version>.tgz
+      // scoped 包格式: @scope-package-name-<version>.tgz
+      const tarball = files.find(f => 
+        f.endsWith('.tgz') && 
+        f.includes(packageName.replace('/', '-'))
+      );
+      
+      if (tarball) {
+        // 解压 tarball
+        await execAsync(`tar -xzf "${path.join(cacheDir, tarball)}" -C "${cacheDir}"`);
+        
+        // 删除 tarball（不再需要）
+        await fs.remove(path.join(cacheDir, tarball));
+        
+        // npm 解压后目录名固定为 'package'，需要重命名为目标版本目录
+        const extractedDir = path.join(cacheDir, 'package');
+        const finalDir = targetDir;
+        
+        // 移动并覆盖（如果已存在）
+        await fs.move(extractedDir, finalDir, { overwrite: true });
+      }
+    } catch (err) {
+      throw new Error(`Failed to download package: ${err}`);
+    }
+  }
+  
+  // ==========================================================================
+  // 步骤 3: 复制到 skills 目录
+  // ==========================================================================
+  
+  const skillsDir = getSkillsDir();
+  
+  // 创建版本目录: ~/.skillmarket/skills/<skillId>@<version>/
+  const skillVersionDir = path.join(skillsDir, `${skillId}@${targetVersion}`);
+  
+  console.log('Setting up skill...');
+  await fs.ensureDir(skillVersionDir);
+  
+  // 从缓存复制必要的文件到 skills 目录
+  const pkgRoot = targetDir;
+  
+  // 复制 SKILL.md（skill 定义文件）
+  if (await fs.pathExists(path.join(pkgRoot, 'SKILL.md'))) {
+    await fs.copy(
+      path.join(pkgRoot, 'SKILL.md'), 
+      path.join(skillVersionDir, 'SKILL.md')
+    );
+  }
+  
+  // 复制 metadata.json（可选元数据文件）
+  if (await fs.pathExists(path.join(pkgRoot, 'metadata.json'))) {
+    await fs.copy(
+      path.join(pkgRoot, 'metadata.json'), 
+      path.join(skillVersionDir, 'metadata.json')
+    );
+  }
+  
+  // ==========================================================================
+  // 步骤 4: 创建 latest 软链接
+  // ==========================================================================
+  
+  // skill 主目录: ~/.skillmarket/skills/<skillId>/
+  const skillDir = path.join(skillsDir, skillId);
+  await fs.ensureDir(skillDir);
+  
+  // latest 软链接路径: ~/.skillmarket/skills/<skillId>/latest
+  const latestLink = path.join(skillDir, LATEST_LINK);
+  
+  try {
+    // 删除已存在的软链接（如果有）
+    await fs.remove(latestLink);
+    
+    // 创建软链接指向版本目录
+    // 'junction' 类型在 Windows 上不需要管理员权限
+    await fs.symlink(skillVersionDir, latestLink, 'junction');
+  } catch {
+    // Windows 上 junction 可能失败，降级为目录复制
+    await fs.copy(skillVersionDir, path.join(skillDir, LATEST_LINK), { overwrite: true });
+  }
+  
+  // ==========================================================================
+  // 步骤 5: 更新注册表
+  // ==========================================================================
+  
+  const registry = await loadRegistry();
+  const currentPlatform = detectPlatform();
+  
+  // 添加/更新注册表中的 skill 记录
+  registry.skills[skillId] = {
+    id: skillId,
+    version: targetVersion,
+    installedAt: new Date().toISOString(),
+    platforms: [currentPlatform]
+  } as InstalledSkill;
+  
+  // 保存注册表
+  await saveRegistry(registry);
+  
+  // ==========================================================================
+  // 完成
+  // ==========================================================================
+  
+  console.log(`\n✅ ${skillId}@${targetVersion} installed successfully!`);
+  console.log(`   Use "skm info ${skillId}" for more details`);
+}

package/src/commands/ls.ts

@@ -0,0 +1,169 @@
+/**
+ * =============================================================================
+ * SkillMarket 列表命令模块
+ * =============================================================================
+ * 
+ * 本模块实现 `skm ls` 命令，用于：
+ * - 列出 npm registry 上可用的 skills
+ * - 显示本地已安装的 skills
+ * 
+ * @module commands/ls
+ */
+
+// -----------------------------------------------------------------------------
+// 导入依赖
+// -----------------------------------------------------------------------------
+
+import { 
+  loadRegistry,          // 加载本地注册表
+  getInstalledSkills     // 获取已安装 skills 列表
+} from './registry.js';
+
+import { 
+  searchSkillmarketPackages,  // 搜索 npm 上的 skill 包
+  fetchNpmPackage             // 获取单个包的详细信息
+} from './npm.js';
+
+// -----------------------------------------------------------------------------
+// 类型定义
+// -----------------------------------------------------------------------------
+
+/**
+ * ls 命令选项接口
+ */
+interface LsOptions {
+  /** 仅显示已安装的 skills */
+  installed?: boolean;
+  
+  /** 检查更新（预留功能） */
+  updates?: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// 命令实现
+// -----------------------------------------------------------------------------
+
+/**
+ * 列出 skills
+ * 
+ * 根据选项显示 npm registry 上可用的 skills
+ * 或本地已安装的 skills
+ * 
+ * @param {LsOptions} options - 命令选项
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * // 列出 npm 上的可用 skills
+ * await listSkills({});
+ * 
+ * // 列出已安装的 skills
+ * await listSkills({ installed: true });
+ */
+export async function listSkills(options: LsOptions): Promise<void> {
+  const { installed, updates } = options;
+  
+  // -------------------------------------------------------------------------
+  // 模式1: 显示已安装的 skills
+  // -------------------------------------------------------------------------
+  if (installed) {
+    const skills = await getInstalledSkills();
+    
+    // 无已安装 skills 时给出提示
+    if (skills.length === 0) {
+      console.log('No skills installed yet. Run "skm --ls" to see available skills.');
+      return;
+    }
+    
+    // 打印表头
+    console.log('Installed Skills:\n');
+    
+    // 遍历并打印每个 skill 的详细信息
+    for (const skill of skills) {
+      // skill 名称和版本
+      console.log(`  ${skill.id}@${skill.version}`);
+      
+      // 支持的平台列表
+      console.log(`    Platforms: ${skill.platforms.join(', ')}`);
+      
+      // 安装时间
+      console.log(`    Installed: ${skill.installedAt}`);
+      
+      // 空行分隔
+      console.log();
+    }
+    
+    return;
+  }
+  
+  // -------------------------------------------------------------------------
+  // 模式2: 显示 npm 上可用的 skills
+  // -------------------------------------------------------------------------
+  
+  // 提示用户正在搜索
+  console.log('Searching npm registry...\n');
+  
+  try {
+    // 调用 npm search API 搜索 skillmarket 相关包
+    const packages = await searchSkillmarketPackages();
+    
+    // 无搜索结果时
+    if (packages.length === 0) {
+      console.log('No skills found. Check back later!');
+      return;
+    }
+    
+    // 打印找到的包数量
+    console.log(`Found ${packages.length} skill(s):\n`);
+    
+    // 遍历每个包，获取详细信息并显示
+    for (const pkgName of packages) {
+      try {
+        const info = await fetchNpmPackage(pkgName);
+        
+        if (!info) {
+          // 如果获取失败，仍然显示包名
+          console.log(`📦 ${pkgName} (信息获取失败)`);
+          console.log();
+          continue;
+        }
+        
+        // 获取最新版本号
+        const latestVersion = info['dist-tags']?.latest || 'unknown';
+        
+        // 获取该版本的详细信息
+        const pkg = info.versions?.[latestVersion];
+        
+        // 获取 skillmarket 元数据
+        const skillMeta = pkg?.skillmarket;
+        
+        // 打印包名和版本
+        console.log(`📦 ${info.name}@${latestVersion}`);
+        
+        // 打印显示名称
+        const displayName = skillMeta?.displayName || info.name;
+        console.log(`   名称: ${displayName}`);
+        
+        // 打印描述
+        console.log(`   描述: ${pkg?.description || 'N/A'}`);
+        
+        // 打印支持平台
+        const platforms = skillMeta?.platforms || [];
+        console.log(`   平台: ${platforms.length > 0 ? platforms.join(', ') : 'N/A'}`);
+        
+        // 打印 npm 链接
+        const npmLink = pkg?.links?.npm || `https://www.npmjs.com/package/${info.name}`;
+        console.log(`   链接: ${npmLink}`);
+        
+        // 空行分隔
+        console.log();
+      } catch (e) {
+        // 错误时仍显示包名
+        console.log(`📦 ${pkgName} (获取失败: ${e})`);
+        console.log();
+      }
+    }
+  } catch (error) {
+    // 网络错误处理
+    console.log(`Error fetching skills: ${error}`);
+  }
+}

package/src/commands/npm.ts

@@ -0,0 +1,261 @@
+/**
+ * =============================================================================
+ * SkillMarket NPM Registry 查询模块
+ * =============================================================================
+ * 
+ * 本模块负责与 npm registry 通信，实现以下功能：
+ * - 获取指定 npm 包的信息
+ * - 搜索带有 skillmarket 关键字的包
+ * 
+ * 使用原生 Node.js https 模块，无需额外依赖。
+ * 
+ * npm Registry API 文档: https://docs.npmjs.com/cli/v8/using-npm/registry
+ * 
+ * @module commands/npm
+ */
+
+// -----------------------------------------------------------------------------
+// 导入依赖
+// -----------------------------------------------------------------------------
+
+import https from 'https';  // Node.js 原生 HTTPS 模块，用于发送 HTTP 请求
+import { URL } from 'url';   // URL 解析和构建工具
+
+// -----------------------------------------------------------------------------
+// 类型定义
+// -----------------------------------------------------------------------------
+
+/**
+ * npm 包版本信息
+ * 
+ * 定义从 npm registry 返回的单个版本对象的结构
+ */
+interface NpmPackage {
+  /** 包名称 */
+  name: string;
+  
+  /** 版本号，遵循 semver 规范 */
+  version: string;
+  
+  /** 包描述信息 */
+  description?: string;
+  
+  /** npm 链接 */
+  links?: {
+    npm?: string;
+    homepage?: string;
+    repository?: string;
+    bugs?: string;
+  };
+  
+  /**
+   * SkillMarket 特有的元数据
+   * 
+   * 在 package.json 的 skillmarket 字段中定义，
+   * 包含 skill 的平台兼容性等信息
+   */
+  skillmarket?: {
+    /** Skill 唯一标识符 */
+    id?: string;
+    
+    /** 友好显示名称 */
+    displayName?: string;
+    
+    /** 详细描述 */
+    description?: string;
+    
+    /** 支持的平台列表 */
+    platforms?: string[];
+    
+    /** 默认版本标识 */
+    defaultVersion?: string;
+  };
+}
+
+/**
+ * npm registry API 响应结构
+ * 
+ * 对应 npm registry 的完整包信息响应
+ */
+interface NpmRegistryResponse {
+  /** 包名称 */
+  name: string;
+  
+  /** 所有版本的字典，key 是版本号 */
+  versions: Record<string, NpmPackage>;
+  
+  /** 发行标签，如 { latest: "1.0.0", beta: "1.1.0-beta.1" } */
+  'dist-tags': Record<string, string>;
+}
+
+/**
+ * npm search API 响应中的包对象
+ */
+interface SearchPackage {
+  /** 包名 */
+  name: string;
+  /** 版本 */
+  version: string;
+}
+
+// -----------------------------------------------------------------------------
+// 获取包信息
+// -----------------------------------------------------------------------------
+
+/**
+ * 获取指定 npm 包的完整信息
+ * 
+ * 向 npm registry API 发送请求，获取包的详细信息，
+ * 包括所有版本、描述、依赖等。
+ * 
+ * API 端点: GET https://registry.npmjs.org/{package}
+ * 
+ * @param {string} packageName - 包名称（支持 @scope/name 格式）
+ * @returns {Promise<NpmRegistryResponse | null>} 包信息，失败返回 null
+ * 
+ * @example
+ * // 获取官方 commander 包信息
+ * const info = await fetchNpmPackage('commander');
+ * if (info) {
+ *   console.log(`最新版本: ${info['dist-tags'].latest}`);
+ * }
+ * 
+ * // 获取 scoped 包
+ * const scoped = await fetchNpmPackage('@skillmarket/brainstorming');
+ */
+export async function fetchNpmPackage(packageName: string): Promise<NpmRegistryResponse | null> {
+  return new Promise((resolve, reject) => {
+    // 构建 npm registry URL
+    // scoped 包（如 @foo/bar）需要特殊处理，保留 @ 符号
+    // @foo/bar -> @foo%2Fbar (URL encoded)
+    const isScoped = packageName.startsWith('@');
+    let encodedName: string;
+    
+    if (isScoped) {
+      // 对 scoped 包进行正确编码：@foo/bar -> @foo%2Fbar
+      const scopeAndName = packageName.substring(1); // 去掉 @
+      const slashIndex = scopeAndName.indexOf('/');
+      if (slashIndex > 0) {
+        const scope = scopeAndName.substring(0, slashIndex);
+        const name = scopeAndName.substring(slashIndex + 1);
+        encodedName = `@${encodeURIComponent(scope)}%2F${encodeURIComponent(name)}`;
+      } else {
+        encodedName = packageName; // fallback
+      }
+    } else {
+      encodedName = encodeURIComponent(packageName);
+    }
+    
+    const url = new URL(`https://registry.npmjs.org/${encodedName}`);
+    
+    // 发送 HTTPS GET 请求
+    const req = https.get(url.toString(), { timeout: 10000 }, (res) => {
+      let data = '';
+      
+      // 收集响应数据
+      res.on('data', chunk => { data += chunk; });
+      
+      res.on('end', () => {
+        try {
+          // 解析 JSON 响应
+          const parsed = JSON.parse(data);
+          
+          // 检查 npm 返回的错误
+          // npm 对于不存在的包也返回 200，但 body 中有 error 字段
+          if (parsed.error) {
+            resolve(null);
+            return;
+          }
+          
+          // 成功解析，返回包信息
+          resolve(parsed);
+        } catch {
+          // JSON 解析失败，返回 null
+          resolve(null);
+        }
+      });
+    });
+    
+    // 处理网络错误
+    req.on('error', reject);
+    
+    // 处理请求超时（10秒）
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+  });
+}
+
+// -----------------------------------------------------------------------------
+// 搜索包
+// -----------------------------------------------------------------------------
+
+/**
+ * 搜索 SkillMarket 相关的 npm 包
+ * 
+ * 使用 npm search API 搜索带有 'skillmarket' 关键字的包
+ * 
+ * API 端点: GET https://registry.npmjs.org/-/v1/search
+ * 
+ * @returns {Promise<string[]>} 匹配的包名数组
+ * 
+ * @example
+ * const packages = await searchSkillmarketPackages();
+ * console.log(`找到 ${packages.length} 个 skill 包`);
+ * packages.forEach(name => {
+ *   console.log(`- ${name}`);
+ * });
+ */
+export async function searchSkillmarketPackages(): Promise<string[]> {
+  const packages: string[] = [];
+  
+  return new Promise((resolve, reject) => {
+    // 构建 search API URL
+    const url = new URL('https://registry.npmjs.org/-/v1/search');
+    
+    // 设置搜索参数
+    // text: 搜索关键字
+    // size: 返回结果数量上限
+    url.searchParams.set('text', 'keywords:skillmarket');
+    url.searchParams.set('size', '100');
+    
+    const req = https.get(url.toString(), { timeout: 10000 }, (res) => {
+      let data = '';
+      
+      // 收集响应数据
+      res.on('data', chunk => { data += chunk; });
+      
+      res.on('end', () => {
+        try {
+          // 解析搜索结果
+          const result = JSON.parse(data);
+          
+          // 提取所有匹配的包名
+          // npm search 返回结构: { objects: [{ package: { name: "..." } }] }
+          if (result.objects) {
+            for (const item of result.objects) {
+              if (item?.package?.name) {
+                packages.push(item.package.name);
+              }
+            }
+          }
+          
+          resolve(packages);
+        } catch {
+          // 解析失败返回空数组
+          resolve([]);
+        }
+      });
+    });
+    
+    // 处理网络错误
+    req.on('error', reject);
+    
+    // 处理请求超时
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+  });
+}