joyskills-cli 0.2.6 → 0.2.7

package/src/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 import { listCommand } from './commands/list.js';
 import { installCommand } from './commands/install.js';
 import { removeCommand } from './commands/remove.js';
@@ -8,14 +11,16 @@ import { teamCommand } from './commands/team.js';
 import { auditCommand } from './commands/audit.js';
 import { statusCommand } from './commands/status.js';
 import { syncCommand } from './commands/sync.js';
+import { upgradeCommand } from './commands/upgrade.js';
 import { readCommand } from './commands/read.js';
+import { manageCommand } from './commands/manage.js';
 
 const program = new Command();
 
 program
   .name('joySkills')
   .description('Team-level skill governance compatible with open skill / Claude Skills')
-  .version('0.1.0');
+  .version(version);
 
 // Add commands
 listCommand(program);
@@ -24,17 +29,10 @@ removeCommand(program);
 teamCommand(program);
 auditCommand(program);
 statusCommand(program);
-
-// OpenSkills compatible commands
-program
-  .command('sync')
-  .description('Sync skills to AGENTS.md (OpenSkills compatible)')
-  .action(syncCommand);
-
-program
-  .command('read <skill-name>')
-  .description('Read skill content (OpenSkills compatible)')
-  .action(readCommand);
+syncCommand(program);
+upgradeCommand(program);
+readCommand(program);
+manageCommand(program);
 
 // Parse arguments
 program.parse();

package/src/local.js

@@ -3,22 +3,15 @@ import * as path from 'path';
 import { LocalSkill } from './types.js';
 
 export class LocalManager {
-  constructor(projectRoot, options = {}) {
+  constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.global = options.global || false;
   }
 
   /**
    * Get local skills directory path
-   * 默认项目级：.agent/skills
-   * 全局：~/.agent/skills
    */
   getSkillsDir() {
-    if (this.global) {
-      const homeDir = process.env.HOME || process.env.USERPROFILE;
-      return path.join(homeDir, '.agent', 'skills');
-    }
-    return path.join(this.projectRoot, '.agent', 'skills');
+    return path.join(this.projectRoot, 'skills');
   }
 
   /**

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 joySkills Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/spec/cli-spec.md

@@ -1,167 +0,0 @@
-## joySkills CLI 规范草案
-
-本规范定义 joySkills 命令行接口（CLI）的主要命令及其语义，重点说明：
-
-- 与 openskill 兼容的命令及行为。
-- joySkills 新增的团队治理相关命令。
-
-实现可以使用任意技术栈，但应遵守本规范中定义的输入/输出语义与副作用约束。
-
-### 1. 命令分类概览
-
-1. **基础管理命令（兼容 openskill）**：
-   - `joySkills list`
-   - `joySkills install`
-   - `joySkills remove`
-   - `joySkills update` / `joySkills upgrade`
-   - `joySkills read`
-
-2. **团队 / Registry 管理命令（joySkills 扩展）**：
-   - `joySkills team add`
-   - `joySkills team sync`
-   - `joySkills team use`
-
-3. **版本与锁定相关命令（joySkills 扩展）**：
-   - `joySkills status`
-   - `joySkills audit`
-
-4. **发布与审批命令（joySkills 扩展）**：
-   - `joySkills publish`
-   - `joySkills approve`
-   - `joySkills deprecate`
-
-### 2. 基础管理命令（兼容 openskill）
-
-#### 2.1 `joySkills list`
-
-- **用途**：列出当前 workspace 可用的 Skills。
-- **行为**：
-  - 聚合本地 `skills/` 目录和绑定 Registry 中的可用 Skill 信息。
-  - 默认仅展示每个 Skill 的名称、描述、当前推荐版本等。
-  - 典型选项：
-    - `--all-versions`：展示每个 Skill 的全部版本及状态。
-    - `--registry <name>`：仅查看指定 Registry 的 Skill 列表。
-
-#### 2.2 `joySkills install <skill>[@version]`
-
-- **用途**：安装某个 Skill 到当前项目的 `skills/` 目录。
-- **行为**：
-  - 未指定版本：
-    - 从当前绑定的 Registry 中选择该 Skill 的“推荐版本”（`recommended == true` 且 `state == approved`）。
-  - 指定版本：
-    - 尝试从 Registry 中查找该版本，默认要求 `state == approved`。
-  - 安装成功后：
-    - 在 `skills/<name>/` 下写入具体文件；
-    - 更新 `joySkills.lock` 中对应条目。
-
-#### 2.3 `joySkills remove <skill>`
-
-- **用途**：从当前项目移除一个 Skill。
-- **行为**：
-  - 删除 `skills/<name>/` 目录（或标记为已移除，具体细节由实现决定）。
-  - 更新 `joySkills.lock`，移除或标记该 Skill。
-
-#### 2.4 `joySkills update` / `joySkills upgrade`
-
-- **用途**：升级一个或多个 Skill 的版本。
-- **行为**：
-  - 不带参数时：
-    - 根据团队策略检查所有已安装 Skills 是否有可用升级版本。
-    - 可以提示用户按交互方式选择要升级的 Targets。
-  - 指定 Skill 时：
-    - 根据策略（如仅 minor/patch）选择目标版本并执行安装，更新 lock。
-
-#### 2.5 `joySkills read <skill>`
-
-- **用途**：查看某个 Skill 的元信息与文档（例如 SKILL.md 内容）。
-- **行为**：
-  - 从本地 `skills/` 目录或 Registry 中读取相关信息。
-  - 输出可读格式，便于在终端中快速了解 Skill 能力。
-
-### 3. 团队 / Registry 管理命令（joySkills 扩展）
-
-#### 3.1 `joySkills team add <name> <git-url>`
-
-- **用途**：在本地注册一个团队 Registry。
-- **行为**：
-  - 将 `<name> -> <git-url>` 记录到 joySkills 的本地配置中。
-  - 首次执行时尝试 clone 对应仓库，并解析其中的 `registry.yaml`。
-
-#### 3.2 `joySkills team sync [<name>]`
-
-- **用途**：同步指定或全部已注册 Registry。
-- **行为**：
-  - 执行 `git fetch/pull` 更新本地缓存。
-  - 重新解析 `registry.yaml`，更新本地索引。
-
-#### 3.3 `joySkills team use <name>`
-
-- **用途**：为当前 workspace 选择默认使用的团队 Registry。
-- **行为**：
-  - 将所选 Registry ID 写入当前 workspace 配置或 `joySkills.lock` 的 `registryBindings` 中。
-  - 后续 `list/install/upgrade` 等命令将默认使用该 Registry。
-
-### 4. 版本与锁定相关命令
-
-#### 4.1 `joySkills status`
-
-- **用途**：查看当前项目所有 Skills 的版本状态。
-- **行为**：
-  - 读取 `joySkills.lock` 与 Registry 索引，输出：
-    - Skill 名称。
-    - 当前版本号。
-    - 版本状态（approved/deprecated 等）。
-    - 是否存在可升级版本。
-
-#### 4.2 `joySkills audit`
-
-- **用途**：审计当前项目是否使用了已废弃或存在风险的 Skill 版本。
-- **行为**：
-  - 对比 `joySkills.lock` 中版本与 Registry 索引中的状态。
-  - 输出：
-    - 所有使用 `deprecated` / 标记安全风险版本的 Skill。
-    - 推荐的升级目标版本（如有）。
-
-### 5. 发布与审批命令
-
-#### 5.1 `joySkills publish <skill>@<version> --registry <name>`
-
-- **用途**：将某个 Skill 版本发布到指定 Registry。
-- **行为**（典型集成方式）：
-  - 通常由 CI 在合并代码后调用：
-    - 校验代码仓库中存在对应的 `skills/<name>/` 与 SKILL.md。
-    - 更新 Registry 仓库中的 `registry.yaml`，新增该版本条目（初始 `state` 可以是 `pending_review` 或 `approved`）。
-
-#### 5.2 `joySkills approve <skill>@<version> --registry <name>`
-
-- **用途**：将某个版本标记为 `approved`，允许团队使用。
-- **行为**：
-  - 校验调用者是否具备 `maintainer` 或以上权限。
-  - 更新 Registry 索引中对应版本的 `state` 与 `approvedBy/approvedAt`。
-
-#### 5.3 `joySkills deprecate <skill>@<version> --registry <name>`
-
-- **用途**：将某个版本标记为 `deprecated`。
-- **行为**：
-  - 更新 Registry 索引中 `state = deprecated`。
-  - 可选：增加推荐替代版本信息，供 `audit` 与升级逻辑使用。
-
-### 6. 与 openskill 的兼容策略
-
-- **命令级兼容**：
-  - joySkills 的基础管理命令（list/install/remove/update/read）应与 openskill 在语义上保持对齐，确保现有使用习惯不被破坏。
-
-- **行为级兼容**：
-  - 对于仅使用本地 `skills/` 目录的场景：
-    - joySkills 可以退化为一个简单的本地管理工具，不依赖 Registry / lockfile。
-  - 对于已有 openskill 的项目：
-    - 只要 joySkills 保证生成的 `skills/` 目录与 openskill 一致，编辑器侧（Claude Code 等）就不需要做任何改动。
-
-### 7. 未来扩展
-
-- 本规范聚焦 v1 所需的最小命令集合。
-- 后续如需扩展（例如：
-  - 更多团队级配置命令；
-  - 与企业 IAM/审计系统对接；
-  - 交互式 TUI / Web UI；
- ），应在保持现有命令语义稳定的前提下新增子命令或选项。

package/spec/lockfile-spec.md

@@ -1,108 +0,0 @@
-## joySkills 锁文件（joySkills.lock）规范草案
-
-本规范定义 joySkills 在项目根目录使用的锁文件 `joySkills.lock`，用于记录当前项目实际使用的 Skills 版本与来源，以支持版本锁定、升级策略和审计能力。
-
-### 1. 概念与目标
-
-- **joySkills.lock 是什么？**
-  - 一个声明式文件，描述“当前项目在实际使用哪些 `skill@version`、这些版本来自哪个 Registry、何时安装的”。
-  - 类似于包管理器中的 lockfile（如 `package-lock.json` / `yarn.lock`），但对象是 AI Skills。
-
-- **设计目标**：
-  - 确保团队内不同成员 / 不同环境在同一项目中使用一致的 Skill 版本。
-  - 为审计工具提供稳定的数据源，用于构建 who-uses-what 视图。
-  - 在不破坏 open skill / openskill 行为的前提下引入版本锁定能力。
-
-### 2. 文件结构（示例）
-
-下面示例采用 YAML 表达，实际可根据技术栈选择 YAML/JSON 等格式，但字段语义应保持一致。
-
-```yaml
-lockVersion: 1
-projectId: "git@company:repo/path.git"   # 可选，用于跨项目聚合
-registryBindings:
-  - registryId: team://growth
-    alias: growth
-  - registryId: org://platform
-    alias: platform
-
-skills:
-  pdf:
-    version: 1.2.0
-    registry: team://growth
-    installedAt: 2025-01-03T09:00:00Z
-  web-testing:
-    version: 0.9.1
-    registry: org://platform
-    installedAt: 2025-01-05T14:30:00Z
-```
-
-### 3. 字段语义
-
-- **顶层字段**：
-  - `lockVersion`：
-    - 锁文件格式版本号，用于未来演进与迁移。
-  - `projectId`（可选）：
-    - 项目标识，用于跨仓库聚合审计数据，推荐使用仓库地址或唯一 ID。
-  - `registryBindings[]`（可选）：
-    - 当前项目绑定的 Registry 列表：
-      - `registryId`：Registry 的唯一标识，例如 `team://growth`。
-      - `alias`：本地别名，可用于 CLI 参数的简写。
-
-- **`skills` 映射**：
-  - key：
-    - Skill 名称，通常与 `skills/<name>/` 目录名一致。
-  - value：
-    - `version`：该项目实际使用的版本号。
-    - `registry`：该版本来源的 Registry ID。
-    - `installedAt`：该版本安装或升级到当前状态的时间戳。
-
-### 4. CLI 行为约定
-
-joySkills CLI 在读写 `joySkills.lock` 时应遵循以下约定：
-
-- `joySkills install <skill>`：
-  - 未指定版本时：
-    - 根据当前绑定 Registry 的推荐版本策略选择一个 `approved` 版本。
-    - 安装成功后，在 `skills` 映射中写入或更新对应条目。
-  - 指定版本时：
-    - 安装指定版本（通常要求版本状态为 `approved` 或显式允许 `deprecated`），并写入 lock。
-
-- `joySkills upgrade <skill>`：
-  - 根据团队策略（例如只允许 minor/patch 升级）与 Registry 索引选择目标版本。
-  - 完成安装后更新 `version` 和 `installedAt` 字段。
-
-- `joySkills status`：
-  - 读取 `joySkills.lock` 中的 `skills` 映射，结合 Registry 索引输出：
-    - 当前 Skill 版本。
-    - 版本状态（approved/deprecated 等）。
-    - 是否有可用升级。
-
-- `joySkills audit`：
-  - 读取 lockfile 与 Registry：
-    - 标记使用 `deprecated` 或被标记为安全风险的版本。
-    - 给出建议的升级目标（如果存在）。
-
-### 5. 生成与更新策略
-
-- 锁文件应当由 joySkills CLI 自动生成与更新，避免手动编辑导致不一致。
-- 当 `skills/` 目录发生变动（通过 joySkills 命令）时，必须同步更新 `joySkills.lock`：
-  - 新增 Skill：添加条目。
-  - 升级 Skill：更新版本号与时间戳。
-  - 移除 Skill：可以选择删除条目或标记为已移除（具体策略由实现决定）。
-
-### 6. 与 openskill / 现有行为的兼容
-
-- 在没有 `joySkills.lock` 的项目中：
-  - joySkills 可以在首次安装时自动生成锁文件；
-  - 若仅使用 openskill，则该文件不存在，不影响其正常工作。
-
-- 共存策略：
-  - 如果一个项目同时使用 openskill 和 joySkills：
-    - 由 joySkills 管理的安装/升级操作应保证与 openskill 期望的目录结构兼容；
-    - openskill 不需要理解 `joySkills.lock`，只要看到正确的 `skills/` 目录即可。
-
-### 7. 演进与迁移
-
-- 锁文件格式演进时，通过提升 `lockVersion` 并提供迁移工具完成升级。
-- 建议新增字段保持向后兼容，旧版本工具在遇到未知字段时应忽略之，而不是报错中止。

package/spec/registry-spec.md

@@ -1,117 +0,0 @@
-## 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` 并提供迁移脚本实现。
-  - 建议所有新增字段保持可选，避免破坏现有实现。