joyskills-cli 0.1.1

package/spec/registry-spec.md

@@ -0,0 +1,117 @@
+## joySkills Registry 规范草案
+
+本规范描述 joySkills 在 open skill / Claude Skills 协议之上的 **团队 / 组织级 Skill Registry 模型**。Registry 负责统一管理可用 Skills 的来源、版本及治理元数据。
+
+### 1. 概念与目标
+
+- **Registry 是什么？**
+  - 一个逻辑上的 Skill 源（Source），对应一组可安装的 Skills 及其元信息。
+  - 物理上通常由一个 Git 仓库 + 一个索引文件（本规范默认使用 `registry.yaml`）实现。
+
+- **设计目标**：
+  - 不改变 `skills/<name>/SKILL.md` 的结构与语义。
+  - 在此之上增加：版本状态、可见性、维护者、推荐版本等治理信息。
+  - 允许多个 Registry 共存（personal / team / org），由 joySkills CLI 统一访问。
+
+### 2. 索引文件结构（示例）
+
+下面示例采用 YAML 表达，仅说明字段含义，实际实现可以选择 YAML/JSON 等等。
+
+```yaml
+registryVersion: 1
+registryId: team://example
+skills:
+  - id: pdf
+    name: "PDF 文档处理"
+    visibility: public          # public | restricted | internal
+    maintainers:
+      - alice
+      - bob
+    versions:
+      - version: 1.2.0
+        state: approved          # draft | pending_review | approved | deprecated | archived
+        createdBy: alice
+        createdAt: 2025-01-01T10:00:00Z
+        approvedBy: bob
+        approvedAt: 2025-01-02T12:00:00Z
+        recommended: true        # 是否为默认推荐版本
+        notes: "修复若干兼容性问题"
+      - version: 1.1.0
+        state: deprecated
+        recommended: false
+        notes: "存在安全风险，建议升级至 >=1.2.0"
+```
+
+### 3. 字段语义
+
+- **顶层字段**：
+  - `registryVersion`：
+    - 索引格式的版本号，用于未来演进（向后兼容 / 迁移策略）。
+  - `registryId`：
+    - 唯一标识一个 Registry，例如：`team://growth`、`org://platform`。
+
+- **`skills[]` 列表**：
+  - `id`：
+    - Skill 标识，一般与 `skills/<id>/` 目录名一致。
+  - `name`：
+    - 人类可读名称，用于 CLI / UI 展示。
+  - `visibility`：
+    - 控制该 Skill 在团队内的可见范围：
+      - `public`：团队/组织内所有用户可见。
+      - `restricted`：仅部分用户/用户组可见（具体规则可由实现扩展）。
+      - `internal`：仅维护者/管理员可见，用于实验性 Skill。
+  - `maintainers[]`：
+    - 维护者用户名列表，用于权限校验与责任归属。
+
+- **`versions[]` 列表**：
+  - `version`：
+    - Skill 的版本号，建议使用 semver（如 `1.2.0`）。
+  - `state`：
+    - 当前版本的治理状态：
+      - `draft`：草稿，通常仅存在于开发分支，不对普通用户开放安装。
+      - `pending_review`：待审核，已提交合并请求或发布请求。
+      - `approved`：已通过审核与自动化校验，允许团队范围使用。
+      - `deprecated`：不再推荐使用，但仍允许安装，用于兼容旧项目。
+      - `archived`：归档，通常不再对外展示，仅保留历史记录。
+  - `recommended`：
+    - 该版本是否为团队默认推荐版本（`true/false`）。
+  - `createdBy` / `createdAt` / `approvedBy` / `approvedAt` / `notes`：
+    - 元数据字段，用于审计与可观测性，不参与核心协议判断。
+
+### 4. 状态机与行为约束
+
+Registry 只记录状态，不强制具体工作流实现；下面是推荐的状态迁移：
+
+- `draft` → `pending_review`：
+  - 开发者完成 Skill 修改，发起代码评审或发布请求。
+- `pending_review` → `approved`：
+  - 审核人与 CI 校验通过，将该版本标记为可用。
+- `approved` → `deprecated`：
+  - 当存在更优版本、或发现风险时，由维护者将旧版本标记为不推荐使用。
+- `deprecated` → `archived`：
+  - 当版本长期不再需要时，出于列表简化与合规因素，将其归档。
+
+joySkills CLI 在读取 Registry 时应遵守以下约束：
+
+- 默认 `list` / `install` 仅展示 / 使用 `approved` 状态中的版本。
+- 安装 `deprecated` 版本时应明确告警，并提示推荐替代版本（如果有）。
+- `draft` 和 `pending_review` 版本仅对维护者 / 管理员可见，普通用户不可见。
+
+### 5. 与 SKILL.md 的边界
+
+- SKILL.md 负责：
+  - 描述 Skill 本身的能力、参数、运行方式等（open skill 协议层）。
+- Registry 索引负责：
+  - 记录该 Skill 在某个团队 / 组织环境下的治理信息：可见性、状态、维护者、推荐版本等。
+
+两者必须通过 `id` 与 `version` 对应，但语义分工清晰，避免相互污染。
+
+### 6. 兼容性与演进
+
+- **向后兼容**：
+  - 在没有 Registry 的场景下，joySkills 可以退化为仅基于本地 `skills/` 目录工作的模式。
+  - 当 Registry 存在但不包含某个 Skill 时，可按 openskill 的行为处理（例如直接从 Git 安装）。
+
+- **向前演进**：
+  - 未来如需扩展字段，可通过提升 `registryVersion` 并提供迁移脚本实现。
+  - 建议所有新增字段保持可选，避免破坏现有实现。

package/src/commands/audit.js

@@ -0,0 +1,78 @@
+import { LockfileManager } from '../lockfile.js';
+import { RegistryManager } from '../registry.js';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export function auditCommand(program) {
+  program
+    .command('audit')
+    .description('Audit installed skills for security and deprecation issues')
+    .action(async () => {
+      const projectRoot = process.cwd();
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log('Skill Audit Report:');
+      console.log('==================');
+
+      try {
+        await lockfileManager.load();
+
+        const installedSkills = lockfileManager.lockData.skills;
+        const skillIds = Object.keys(installedSkills);
+
+        if (skillIds.length === 0) {
+          console.log('No skills installed.');
+          return;
+        }
+
+        // Check for registry
+        const registryPath = path.join(projectRoot, '.joyskill/registry');
+        let registryManager = null;
+
+        if (fs.existsSync(registryPath)) {
+          try {
+            registryManager = new RegistryManager(registryPath);
+            await registryManager.load();
+          } catch (error) {
+            console.error('Warning: Could not load registry:', error.message);
+          }
+        }
+
+        let hasIssues = false;
+
+        for (const skillId of skillIds) {
+          const skillEntry = installedSkills[skillId];
+
+          if (registryManager) {
+            const skill = registryManager.getSkill(skillId);
+            if (skill) {
+              const version = registryManager.getVersion(skillId, skillEntry.version);
+              if (version) {
+                if (version.state === 'deprecated') {
+                  hasIssues = true;
+                  console.log(`\n⚠️  ${skillId} v${skillEntry.version} is DEPRECATED`);
+
+                  const recommended = registryManager.getRecommendedVersion(skillId);
+                  if (recommended) {
+                    console.log(`   Recommended: Upgrade to v${recommended.version}`);
+                  }
+                } else if (version.state === 'draft' || version.state === 'pending_review') {
+                  hasIssues = true;
+                  console.log(`\n❌ ${skillId} v${skillEntry.version} is in ${version.state} state`);
+                  console.log(`   This version may not be stable or approved for production use.`);
+                }
+              }
+            }
+          }
+        }
+
+        if (!hasIssues) {
+          console.log('\n✅ All installed skills are in good standing.');
+        } else {
+          console.log('\n🔍 Review the issues above and consider updating affected skills.');
+        }
+      } catch (error) {
+        console.error('Error during audit:', error);
+      }
+    });
+}

package/src/commands/install.js

@@ -0,0 +1,119 @@
+import { Command } from 'commander';
+import { LocalManager } from '../local.js';
+import { LockfileManager } from '../lockfile.js';
+import { RegistryManager } from '../registry.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function installCommand(program) {
+  program
+    .command('install <skill>')
+    .description('Install a skill')
+    .option('-v, --version <version>', 'Specify version to install')
+    .option('-r, --registry <name>', 'Install from specific registry')
+    .option('--force', 'Force installation even if version is not recommended')
+    .action(async (skillName, options) => {
+      const projectRoot = process.cwd();
+      const localManager = new LocalManager(projectRoot);
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log(`Installing skill: ${skillName}`);
+
+      try {
+        // Load existing lockfile if exists
+        await lockfileManager.load();
+
+        // Check if skill already exists
+        if (localManager.hasSkill(skillName)) {
+          console.log(`⚠️  Skill ${skillName} already exists locally.`);
+          console.log('   Use "joyskill remove <skill>" first if you want to reinstall.');
+          return;
+        }
+
+        // Check for registry
+        let registryManager = null;
+        const registryPath = path.join(projectRoot, '.joyskill/registry');
+
+        if (fs.existsSync(registryPath)) {
+          try {
+            registryManager = new RegistryManager(registryPath);
+            await registryManager.load();
+          } catch (error) {
+            console.error('Warning: Could not load registry:', error.message);
+          }
+        }
+
+        // Determine version to install
+        let targetVersion = options.version || '1.0.0';
+        let versionSource = 'default';
+
+        if (registryManager && registryManager.hasSkill(skillName)) {
+          if (!options.version) {
+            // Get recommended version from registry
+            const recommended = registryManager.getRecommendedVersion(skillName);
+            if (recommended) {
+              targetVersion = recommended.version;
+              versionSource = 'registry';
+            }
+          }
+
+          // Validate version
+          const validation = registryManager.validateVersion(skillName, targetVersion);
+          if (!validation.valid && !options.force) {
+            console.error(`❌ Version validation failed: ${validation.error}`);
+            return;
+          }
+
+          if (validation.warning && !options.force) {
+            console.log(`⚠️  Warning: ${validation.warning}`);
+            console.log('   Use --force to install anyway.');
+            return;
+          }
+
+          console.log(`Installing ${skillName} v${targetVersion} from registry`);
+        } else {
+          console.log(`Installing ${skillName} v${targetVersion} (local/custom)`);
+        }
+
+        // Create sample SKILL.md content
+        const skillMdContent = `---
+name: ${skillName}
+description: Auto-generated skill for ${skillName}
+version: ${targetVersion}
+---
+
+# ${skillName}
+
+This skill was automatically generated by joyskill.
+
+## Examples
+- Example usage 1
+- Example usage 2
+
+## Guidelines
+- Guideline 1
+- Guideline 2
+`;
+
+        // Install the skill
+        localManager.installSkill(skillName, skillMdContent);
+
+        // Update lockfile
+        lockfileManager.updateSkill(skillName, {
+          version: targetVersion,
+          registry: options.registry || 'local',
+          installedAt: new Date().toISOString()
+        });
+
+        await lockfileManager.save();
+
+        console.log(`✅ Successfully installed ${skillName} v${targetVersion}`);
+
+        if (versionSource === 'registry') {
+          console.log('   Version selected from registry recommendations.');
+        }
+      } catch (error) {
+        console.error(`❌ Failed to install ${skillName}:`, error);
+      }
+    });
+}

package/src/commands/list.js

@@ -0,0 +1,120 @@
+import { LocalManager } from '../local.js';
+import { RegistryManager } from '../registry.js';
+import { LockfileManager } from '../lockfile.js';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export function listCommand(program) {
+  program
+    .command('list')
+    .description('List available skills')
+    .option('-a, --all-versions', 'Show all versions of each skill')
+    .option('-c, --category <category>', 'Filter by category')
+    .option('-s, --search <query>', 'Search skills by name or description')
+    .option('-i, --installed', 'Show only installed skills')
+    .option('-l, --local', 'Show only local skills')
+    .option('-r, --registry <name>', 'Show skills from specific registry')
+    .action(async (options) => {
+      const projectRoot = process.cwd();
+      const localManager = new LocalManager(projectRoot);
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log('Available Skills:');
+      console.log('=================');
+
+      try {
+        // Load lockfile to know what's installed
+        await lockfileManager.load();
+        const installedSkills = lockfileManager.lockData.skills;
+
+        // List local skills
+        const localSkills = localManager.listSkills();
+
+        if (!options.registry) {
+          // Show local skills if requested or if local-only mode
+          if (options.local || localSkills.length > 0) {
+            console.log('\nLocal Skills:');
+            const filteredLocalSkills = localSkills.filter(skill => {
+              if (options.installed && !installedSkills[skill]) return false;
+              if (options.search) {
+                const query = options.search.toLowerCase();
+                return skill.toLowerCase().includes(query);
+              }
+              return true;
+            });
+
+            if (filteredLocalSkills.length > 0) {
+              filteredLocalSkills.forEach(skill => {
+                const isInstalled = installedSkills[skill] ? '✅' : '  ';
+                const version = installedSkills[skill] ? `v${installedSkills[skill].version}` : '';
+                console.log(`  ${isInstalled} ${skill} ${version}`);
+              });
+            } else {
+              console.log('  No matching local skills found.');
+            }
+          }
+        }
+
+        // Check for registry
+        const registryPath = path.join(projectRoot, '.joyskill/registry');
+        if (fs.existsSync(registryPath) && !options.local) {
+          try {
+            const registryManager = new RegistryManager(registryPath);
+            await registryManager.load();
+
+            console.log('\nRegistry Skills:');
+
+            let skills = registryManager.getAllSkills();
+
+            // Apply filters
+            if (options.category) {
+              skills = registryManager.getSkillsByCategory(options.category);
+            }
+
+            if (options.search) {
+              skills = registryManager.searchSkills(options.search);
+            }
+
+            if (options.installed) {
+              skills = skills.filter(skill => installedSkills[skill.id]);
+            }
+
+            if (skills.length > 0) {
+              skills.forEach(skill => {
+                const isInstalled = installedSkills[skill.id] ? '✅' : '  ';
+                const installedVersion = installedSkills[skill.id]?.version;
+
+                // Get recommended version
+                const recommended = registryManager.getRecommendedVersion(skill.id);
+                const recommendedVersion = recommended ? recommended.version : 'N/A';
+
+                console.log(`  ${isInstalled} ${skill.name || skill.id} (${skill.id})`);
+                if (options.allVersions) {
+                  skill.versions.forEach(v => {
+                    const marker = v.recommended ? '⭐' : '  ';
+                    const state = v.state === 'approved' ? '✓' : v.state;
+                    console.log(`      ${marker} v${v.version} [${state}]`);
+                  });
+                } else {
+                  console.log(`      Recommended: v${recommendedVersion}`);
+                  if (installedVersion) {
+                    console.log(`      Installed: v${installedVersion}`);
+                  }
+                }
+                if (skill.description) {
+                  console.log(`      ${skill.description}`);
+                }
+                console.log('');
+              });
+            } else {
+              console.log('  No matching registry skills found.');
+            }
+          } catch (error) {
+            console.error('Error loading registry:', error.message);
+          }
+        }
+      } catch (error) {
+        console.error('Error listing skills:', error);
+      }
+    });
+}

package/src/commands/remove.js

@@ -0,0 +1,42 @@
+import { Command } from 'commander';
+import { LocalManager } from '../local.js';
+import { LockfileManager } from '../lockfile.js';
+
+export function removeCommand(program) {
+  program
+    .command('remove <skill>')
+    .description('Remove a skill')
+    .action(async (skillName) => {
+      const projectRoot = process.cwd();
+      const localManager = new LocalManager(projectRoot);
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log(`Removing skill: ${skillName}`);
+
+      try {
+        // Load existing lockfile if exists
+        await lockfileManager.load();
+
+        // Check if skill exists locally
+        if (!localManager.hasSkill(skillName)) {
+          console.log(`Skill ${skillName} does not exist locally.`);
+          return;
+        }
+
+        // Remove the skill
+        const removed = localManager.removeSkill(skillName);
+
+        if (removed) {
+          // Update lockfile
+          lockfileManager.removeSkill(skillName);
+          await lockfileManager.save();
+
+          console.log(`✅ Successfully removed ${skillName}`);
+        } else {
+          console.log(`❌ Failed to remove ${skillName}`);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to remove ${skillName}:`, error);
+      }
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,116 @@
+import { LockfileManager } from '../lockfile.js';
+import { RegistryManager } from '../registry.js';
+import { LocalManager } from '../local.js';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export function statusCommand(program) {
+  program
+    .command('status')
+    .description('Show the current status of skills in the project')
+    .action(async () => {
+      const projectRoot = process.cwd();
+      const lockfileManager = new LockfileManager(projectRoot);
+      const localManager = new LocalManager(projectRoot);
+
+      console.log('Skill Status Report:');
+      console.log('====================');
+
+      try {
+        await lockfileManager.load();
+
+        const installedSkills = lockfileManager.lockData.skills;
+        const skillIds = Object.keys(installedSkills);
+
+        if (skillIds.length === 0) {
+          console.log('No skills installed.');
+          return;
+        }
+
+        // Check for registry
+        const registryPath = path.join(projectRoot, '.joyskill/registry');
+        let registryManager = null;
+
+        if (fs.existsSync(registryPath)) {
+          try {
+            registryManager = new RegistryManager(registryPath);
+            await registryManager.load();
+          } catch (error) {
+            console.error('Warning: Could not load registry:', error.message);
+          }
+        }
+
+        console.log(`\nInstalled Skills (${skillIds.length} total):`);
+        console.log('------------------------------');
+
+        for (const skillId of skillIds) {
+          const skillEntry = installedSkills[skillId];
+
+          let status = '✅ Installed';
+          let details = '';
+
+          // Check if skill exists locally
+          const hasLocal = localManager.hasSkill(skillId);
+
+          // Check registry status
+          if (registryManager) {
+            const skill = registryManager.getSkill(skillId);
+            if (skill) {
+              const version = registryManager.getVersion(skillId, skillEntry.version);
+              if (version) {
+                if (version.state === 'deprecated') {
+                  status = '⚠️  Deprecated';
+                  details = ' (upgrade recommended)';
+                } else if (version.state === 'draft' || version.state === 'pending_review') {
+                  status = '❌ Not Approved';
+                  details = ` (${version.state})`;
+                }
+
+                // Check for newer versions
+                const latest = registryManager.getLatestVersion(skillId);
+                if (latest && latest.version !== skillEntry.version) {
+                  details += ` - newer version v${latest.version} available`;
+                }
+              }
+            } else {
+              status = '❓ Not in Registry';
+              details = ' (local/external skill)';
+            }
+          }
+
+          if (!hasLocal) {
+            status = '⚠️  Missing Local Files';
+            details = ' (files may have been deleted)';
+          }
+
+          console.log(`${skillId} v${skillEntry.version}: ${status}${details}`);
+        }
+
+        // Show registry info
+        if (registryManager) {
+          console.log('\nRegistry Status:');
+          console.log('---------------');
+          console.log(`Registry loaded from: ${registryPath}`);
+          console.log(`Total skills in registry: ${registryManager.getAllSkills().length}`);
+        } else {
+          console.log('\nRegistry Status:');
+          console.log('---------------');
+          console.log('No registry found. Using local skills only.');
+        }
+
+        // Show local skills
+        const localSkills = localManager.listSkills();
+        const localOnlySkills = localSkills.filter(skillId => !installedSkills[skillId]);
+
+        if (localOnlySkills.length > 0) {
+          console.log(`\nLocal Skills (${localOnlySkills.length} not installed):`);
+          console.log('-------------------------');
+          for (const skillId of localOnlySkills) {
+            console.log(`${skillId} (local only)`);
+          }
+        }
+      } catch (error) {
+        console.error('Error checking status:', error);
+      }
+    });
+}

package/src/commands/team.js

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import { LockfileManager } from '../lockfile.js';
+
+export function teamCommand(program) {
+  const teamProgram = program
+    .command('team')
+    .description('Team registry management');
+
+  teamProgram
+    .command('add <name> <path>')
+    .description('Add a team registry')
+    .action(async (name, path) => {
+      const projectRoot = process.cwd();
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log(`Adding team registry: ${name} -> ${path}`);
+
+      try {
+        await lockfileManager.load();
+        lockfileManager.bindRegistry(path, name);
+        await lockfileManager.save();
+        console.log(`✅ Successfully added registry ${name}`);
+      } catch (error) {
+        console.error(`❌ Failed to add registry:`, error);
+      }
+    });
+
+  teamProgram
+    .command('remove <name>')
+    .description('Remove a team registry')
+    .action(async (name) => {
+      const projectRoot = process.cwd();
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log(`Removing team registry: ${name}`);
+
+      try {
+        await lockfileManager.load();
+        lockfileManager.unbindRegistry(name);
+        await lockfileManager.save();
+        console.log(`✅ Successfully removed registry ${name}`);
+      } catch (error) {
+        console.error(`❌ Failed to remove registry:`, error);
+      }
+    });
+
+  teamProgram
+    .command('list')
+    .description('List team registries')
+    .action(async () => {
+      const projectRoot = process.cwd();
+      const lockfileManager = new LockfileManager(projectRoot);
+
+      console.log('Team Registries:');
+      console.log('================');
+
+      try {
+        await lockfileManager.load();
+
+        const registries = lockfileManager.lockData.registries || {};
+        const registryNames = Object.keys(registries);
+
+        if (registryNames.length === 0) {
+          console.log('No team registries configured.');
+          return;
+        }
+
+        for (const name of registryNames) {
+          const registry = registries[name];
+          console.log(`${name}: ${registry.path}`);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to list registries:`, error);
+      }
+    });
+
+  teamProgram
+    .command('sync [name]')
+    .description('Sync team registry')
+    .action(async (name) => {
+      console.log(`Syncing registry: ${name || 'all'}`);
+      console.log('(Registry sync functionality coming soon)');
+    });
+
+  teamProgram
+    .command('use <name>')
+    .description('Set default team registry')
+    .action(async (name) => {
+      console.log(`Setting default registry to: ${name}`);
+      console.log('(Registry use functionality coming soon)');
+    });
+}