@42ailab/42plugin 0.1.0-beta.1 → 0.1.2

package/README.md

@@ -1,101 +1,244 @@
 # 42plugin CLI
 
-活水插件，支持搜索、安装、管理来自 42plugin 平台的能力、插件与插件列表。
+活水插件命令行工具，支持搜索、安装、管理来自 42plugin 平台的插件。
+
+**扁平化架构**：每个 plugin 就是一个 capability (1:1)，简化数据模型。
 
 ## 前提条件
-- 需要安装 [Bun](https://bun.sh)（用于运行与构建）。
-- Node.js/npm 非必需；依赖通过 `bun install` 处理。
 
-## 安装依赖
+- 需要安装 [Bun](https://bun.sh)（用于运行与构建）
+- Node.js/npm 非必需，依赖通过 `bun install` 处理
+
+## 快速开始
+
 ```bash
+# 安装依赖
 bun install
+
+# 开发运行
+bun run dev -- <command> [options]
+
+# 或直接运行
+bun run src/index.ts <command> [options]
+
+# 构建跨平台可执行文件
+bun run build
+# 输出位于 dist/ 下
+```
+
+## 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| TypeScript | 5.7.0 | 类型安全 |
+| Bun | 1.0+ | 运行时和包管理 |
+| Commander.js | 13.0.0 | CLI 框架 |
+| @libsql/client | 0.14.0 | SQLite 数据库 |
+| better-auth | 1.4.6 | 认证客户端 |
+| chalk | 5.4.1 | 终端颜色 |
+| ora | 8.1.1 | 加载动画 |
+
+## 目录结构
+
+```
+42plugin-cli/
+├── src/
+│   ├── index.ts              # 入口文件
+│   ├── cli.ts                # 命令定义
+│   ├── config.ts             # 配置管理
+│   ├── commands/             # CLI 子命令
+│   │   ├── auth.ts           # 登录/授权/登出
+│   │   ├── search.ts         # 搜索
+│   │   ├── install.ts        # 安装
+│   │   ├── list.ts           # 查看已安装
+│   │   ├── uninstall.ts      # 卸载
+│   │   ├── version.ts        # 版本
+│   │   └── publish.ts        # 发布（开发中）
+│   ├── services/             # 业务逻辑
+│   │   ├── api.ts            # API 客户端
+│   │   ├── auth.ts           # 凭证管理
+│   │   ├── download.ts       # 下载处理
+│   │   ├── cache.ts          # 缓存管理
+│   │   ├── link.ts           # 符号链接
+│   │   └── project.ts        # 项目注册
+│   ├── db/
+│   │   └── client.ts         # 数据库客户端
+│   ├── types/                # 类型定义
+│   └── utils/                # 工具函数
+├── tests/                    # 测试用例
+└── scripts/                  # 构建脚本
+```
+
+## CLI 命令
+
+### 认证
+
+使用 Better Auth Device Authorization Flow (RFC 8628)：
+
+```bash
+42plugin auth              # 浏览器授权登录
+42plugin auth --status     # 查看登录状态
+42plugin auth --logout     # 登出并清除本地凭证
 ```
 
-## 本地开发与运行
-- 直接运行入口（便于调试）：
-  ```bash
-  bun run src/index.ts <command> [options]
-  ```
-- 或使用脚本（等同于上方）：
-  ```bash
-  bun run dev -- <command> [options]
-  ```
-- 构建跨平台可执行文件：
-  ```bash
-  bun run build
-  # 输出位于 dist/ 下，如 dist/42plugin-darwin-arm64、dist/42plugin-linux-x64 等
-  ```
-  构建后二进制即可直接执行，例如 `./dist/42plugin-darwin-arm64 search claude`。
-
-## CLI 使用
-### 登录
-- 浏览器授权登录：`42plugin auth`
-- 查看状态：`42plugin auth --status`
-- 登出并清理凭证：`42plugin auth --logout`
-
-### 搜索插件/能力/列表
+### 搜索
+
 ```bash
-42plugin search <关键词> [--type skill|agent|command|hook|list] [--limit 50] [--json]
+42plugin search <关键词> [--type skill|agent|command|hook|kit] [--limit 20] [--json]
 ```
 
 ### 安装
-支持的安装目标格式：
-- 能力：`owner/repo:plugin:type:name`
-- 插件（带插件名）：`owner/repo:plugin`
-- 简化插件：`owner/plugin`
-- 列表：`owner/list/<slug>`
 
-常用示例：
+安装格式：
+
+| 格式 | 说明 |
+|------|------|
+| `author/name` | 安装插件 |
+| `author/kit/slug` | 安装套包 |
+
 ```bash
-42plugin install user/repo:cool-plugin
-42plugin install user/repo:cool-plugin:command:deploy
-42plugin install user/list/tools              # 安装列表（默认只装必选项）
-42plugin install user/list/tools --optional   # 包含列表中的可选项
+# 安装插件
+42plugin install alice/smart-reviewer
+
+# 安装套包
+42plugin install user/kit/tools              # 仅安装必选项
+42plugin install user/kit/tools --optional   # 包含可选项
+
+# 安装某个插件所属的整个套包
+42plugin install alice/smart-reviewer -k
 ```
 
 选项：
-- `-g, --global`：仅下载到缓存，不链接到当前项目。
-- `--force`：忽略缓存，强制重新下载。
-- `--no-cache`：跳过缓存命中检查。
-- `--optional`：安装列表时包含可选能力（默认只安装必选）。
+- `-g, --global`：仅下载到缓存，不链接到当前项目
+- `-k, --kit`：安装该插件所属的整个套包
+- `--optional`：安装套包时包含可选项
+- `--force`：强制重新下载
+- `--no-cache`：跳过缓存命中检查
+- `--from <source>`：指定来源套件
 
-安装会将包解压到本地缓存，再在当前工作目录创建链接到具体安装路径（例如 `.claude/` 下），同时在本地数据库记录。请在项目根目录执行。
+### 管理
 
-### 查看已安装
 ```bash
-42plugin list [--type <type>] [--json]
+42plugin list                        # 查看已安装
+42plugin list --type skill --json
+42plugin uninstall <full_name>       # 卸载
+42plugin uninstall <full_name> --purge
+42plugin version                     # 版本
 ```
 
-### 卸载
+### 发布（开发中）
+
 ```bash
-42plugin uninstall <full_name> [--purge]
+42plugin publish [path]    # 发布插件
+42plugin publish --dry-run # 仅检查，不实际发布
 ```
-`--purge` 会同时删除缓存内容。
 
-### 查看版本
+发布前置条件：
+- 用户必须登录
+- 用户必须验证手机号
+- 用户必须设置 username
+
+## 数据存储
+
+| 类型 | 路径 |
+|------|------|
+| 数据库 | `~/.42plugin/local.db`（Windows: `%APPDATA%/42plugin/local.db`） |
+| 缓存 | `~/.42plugin/cache` |
+| 登录凭证 | `~/.42plugin/secrets.json`（权限 600） |
+| 项目链接 | `.claude/`（项目目录下） |
+
+## 本地数据库表（SQLite）
+
+| 表名 | 说明 |
+|------|------|
+| `projects` | 本地项目注册（id, path, name, registered_at, last_used_at）|
+| `plugin_cache` | 插件下载缓存（full_name, type, version, cache_path, checksum）|
+| `project_plugins` | 项目已安装的插件（project_id, full_name, type, version, link_path, source）|
+| `config` | 配置项（key-value）|
+
+注意：这些表仅在 SQLite 模式下创建，PostgreSQL 模式会跳过以避免污染云端数据库。
+
+## 环境变量
+
 ```bash
-42plugin version
+# API 配置
+API_BASE_URL=https://42plugin.com/api
+CDN_BASE=https://cdn.42plugin.com
+
+# 调试
+DEBUG=true
+
+# 数据库（可选，使用 PostgreSQL 替代默认 SQLite）
+CLI_DB_DRIVER=postgres
+CLI_DATABASE_URL=postgresql://user@localhost:5432/42plugin_local
 ```
 
-## 数据存储位置
-- 配置与数据库：`~/.42plugin/local.db`（Windows 为 `%APPDATA%/42plugin/local.db`）
-- 缓存：`~/.42plugin/cache`
-- 登录凭证：`~/.42plugin/secrets.json`（权限 600）
+## 认证流程
+
+```
+CLI                              API                              Browser
+ │                                │                                   │
+ │─────POST /api/auth/device/code─────>│                               │
+ │<────{device_code, user_code}────────│                               │
+ │                                │                                   │
+ │  显示 user_code 和 verification_uri  │                               │
+ │───────────────────────────────────────────────────────────>│
+ │                                │          用户输入 user_code 并授权  │
+ │                                │<──────────────────────────────────│
+ │                                │                                   │
+ │─────POST /api/auth/device/token──>│                                │
+ │        (轮询，5s 间隔)           │                                   │
+ │<────{access_token, user}─────────│                                 │
+ │                                │                                   │
+ │  保存到 secrets.json            │                                   │
+```
+
+## 安装流程
+
+```
+1. 解析安装目标格式（utils/target.ts）
+   - author/name → TargetType.Plugin
+   - author/kit/slug → TargetType.Kit
+
+2. 从 API 获取下载信息
+   - GET /v1/plugins/{author}/{name}/download
+   - GET /v1/kits/{username}/kit/{slug}/download
+
+3. 检查本地缓存（plugin_cache 表）
+
+4. 从 CDN 下载 tarball
+
+5. 验证 SHA256 校验和
+
+6. 解压到缓存目录 (~/.42plugin/cache)
+
+7. 创建符号链接到项目 .claude/ 目录
+
+8. 记录到本地数据库（project_plugins 表）
+```
+
+## API 端点
+
+### 认证 & 用户
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/auth/device/code` | POST | 请求 device code |
+| `/api/auth/device/token` | POST | 轮询 token |
+| `/api/auth/get-session` | GET | 获取用户会话 |
+| `/api/user/installed` | POST | 同步安装记录 |
+| `/api/user/installed/{author}/{name}` | DELETE | 同步卸载记录 |
+
+### 业务 API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/v1/plugins/{author}/{name}/download` | GET | 获取插件下载信息 |
+| `/v1/kits/{username}/kit/{slug}/download` | GET | 获取套包下载信息 |
+| `/v1/search?q=` | GET | 搜索 |
+
+## 开发命令
 
-## 环境变量
-- `API_BASE`：替换默认的 API 地址（默认 `https://api.42plugin.com`）。
-- `CDN_BASE`：替换默认的 CDN 地址（默认 `https://cdn.42plugin.com`）。
-- `DEBUG=true`：输出调试信息与原始错误。
-- `CLI_DB_DRIVER=postgres`：让 CLI 使用 Postgres 而非默认的本地 SQLite（`~/.42plugin/local.db`）。配合 `CLI_DATABASE_URL` 或 `LOCAL_DATABASE_URL` 指定连接串，例如 `postgresql://postgres:password@localhost:5432/42plugin_cli_dev`。
-
-## 项目结构速览
-- `src/cli.ts`：命令定义与统一入口。
-- `src/commands/*`：各子命令实现（auth、install、search、list、uninstall、version）。
-- `src/services/*`：API、缓存、下载、项目记录、链接创建等核心逻辑。
-- `src/db/client.ts`：本地 SQLite 初始化与连接（基于 @libsql/client）。
-- `tests/`：命令与服务的测试用例。
-
-## 常用开发命令
 ```bash
 bun test              # 运行测试
 bun run lint          # ESLint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@42ailab/42plugin",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.2",
   "description": "活水插件",
   "type": "module",
   "main": "src/index.ts",
@@ -12,12 +12,12 @@
     "README.md"
   ],
   "scripts": {
-    "dev": "bun run --env-file=../.env --env-file=.env src/index.ts",
-    "build": "bun run --env-file=../.env --env-file=.env scripts/build.ts",
-    "test": "bun run --env-file=../.env --env-file=.env test",
-    "lint": "eslint --env-file=../.env --env-file=.env src/",
-    "format": "prettier --write --env-file=../.env --env-file=.env src/",
-    "typecheck": "tsc --noEmit --env-file=../.env --env-file=.env"
+    "dev": "bun run --env-file=../../.env --env-file=.env src/index.ts",
+    "build": "bun run --env-file=../../.env --env-file=.env scripts/build.ts",
+    "test": "bun run --env-file=../../.env --env-file=.env test",
+    "lint": "eslint --env-file=../../.env --env-file=.env src/",
+    "format": "prettier --write --env-file=../../.env --env-file=.env src/",
+    "typecheck": "tsc --noEmit --env-file=../../.env --env-file=.env"
   },
   "keywords": [
     "claude",
@@ -41,9 +41,13 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@inquirer/prompts": "^8.1.0",
     "@libsql/client": "^0.14.0",
+    "better-auth": "^1.4.6",
     "chalk": "^5.4.1",
+    "cli-progress": "^3.12.0",
     "commander": "^13.0.0",
+    "gray-matter": "^4.0.3",
     "nanoid": "^5.0.9",
     "open": "^10.1.0",
     "ora": "^8.1.1",
@@ -52,6 +56,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/cli-progress": "^3.11.6",
     "@types/tar": "^6.1.13",
     "typescript": "^5.7.0"
   }