Plugnix CLI

Plugnix CLI 是 Plugnix 框架的脚手架工具，用于初始化项目并按需集成插件（源码拷贝），同时将插件的数据库迁移脚本纳入到项目的 supabase/migrations 目录中。

安装与运行

• 全局安装：npm i -g plugnix-cli，然后运行 plugnix-cli
• npx：npx plugnix-cli <command>

命令

init

• 功能：使用官方模板创建一个新的 Plugnix 项目骨架。
• 别名：create、new
• 用法示例：
  • plugnix-cli init my-admin
  • node bin/plugnix-cli.js init my-admin
• 执行流程：
  • 使用 degit 从模板仓库 vincent-ng/plugnix 拉取项目到 <project-name> 目录。
  • 完成后输出下一步指引：进入目录、安装依赖、（可选）supabase init。

add <plugin...>

• 功能：从插件仓库下载并集成一个或多个插件到项目中。
• 选项：
  • --registry, -r <url> 指定插件仓库地址，支持本地目录（绝对/相对/file://），默认 github:vincent-ng/plugnix-plugins。
  • --force 若目标插件目录已存在则覆盖（危险操作，请谨慎）。
• 用法示例：
  • 添加官方插件：plugnix-cli add dashboard
  • 一次添加多个：plugnix-cli add analytics user-management
  • 使用社区仓库：plugnix-cli add community-calendar --registry=github:some-community/plugnix-extras
  • 使用公司私有 GitLab：plugnix-cli add internal-billing [email protected]:my-company/plugnix-private-plugins.git
  • 使用本地目录（绝对路径）：plugnix-cli add dashboard --registry="C:\\workspace\\plugnix\\src\\plugins"
  • 使用本地目录（相对路径）：plugnix-cli add dashboard --registry="..\\..\\plugnix\\src\\plugins"
  • 使用本地目录（file 协议）：plugnix-cli add dashboard --registry="file:///C:/workspace/plugnix/src/plugins"
  • 覆盖已存在目录：plugnix-cli add dashboard --registry="C:\\workspace\\plugnix\\src\\plugins" --force
• 执行流程：
  • 解析 registry 与 plugin：
    • 若为本地目录：直接复制 <registry>/<plugin> 到 src/plugins/<plugin>（跳过 node_modules 与 .git）。
    • 若为 Git 源：构造地址（如 github:vincent-ng/plugnix-plugins/dashboard），使用 degit 下载源码。
  • 读取插件 package.json，收集其 dependencies 和 devDependencies。
  • 在所有插件处理完成后，统一将依赖合并到项目的 package.json 中（避免重复依赖和版本冲突）。
  • 输出安装提示，建议用户手动运行包管理器命令安装依赖（如 npm install）。
  • 检查并复制迁移脚本 supabase/migrations/<filename>.sql 到项目 supabase/migrations/YYYYMMDDHHMMSS_<plugin>_<filename>.sql（同秒冲突自动追加序号以保证唯一）。
  • 输出结果与后续建议（如运行 supabase db push）。

选项

• -v, --verbose 输出更详细的调试信息（包括 degit 的 info 日志、错误堆栈）。

插件仓库结构约定

• 仓库示例：https://github.com/vincent-ng/plugnix-plugins
• 目录结构：
  • <plugin>/index.js 插件前端入口（示例）
  • <plugin>/package.json 声明插件依赖
  • <plugin>/supabase/migrations/init.sql 数据库初始化脚本（推荐；缺失时将跳过迁移复制）

数据库迁移

• 添加插件后，迁移文件会被复制到项目的 supabase/migrations 目录。
• 运行迁移：supabase db push
• 如需回滚，请参考插件中的 down.sql（手动处理）。

常见问题

• 私有仓库下载失败：
  • 请确认使用 SSH 地址（形如 git@...）。
  • 确保本机已配置 SSH key 并具备仓库访问权限。
• GitHub 下载失败：
  • 检查网络代理/企业防火墙设置。
  • 多次重试或在稳定网络环境下执行。
• chalk 报错：
  • 本工具使用 ESM 与 chalk@5，请确认 Node 版本满足要求（建议 >= 18）。
• 插件依赖与项目冲突：
  • 工具会将插件依赖合并到项目的 package.json 中，若版本冲突请在项目 package.json 中手动协调。
  • 只有项目中不存在的依赖才会被添加，已存在的依赖版本不会被覆盖。
• 插件目录已存在：
  • 使用 --force 覆盖，或先删除 src/plugins/<plugin> 后重试。
• 依赖安装：
  • 工具不再自动安装依赖，而是将依赖添加到 package.json 后提示用户手动安装。
  • 这样可以避免因依赖安装失败导致项目处于不一致状态，同时给予用户更多控制权。
  • 请按照工具提示运行相应的包管理器命令（如 npm install、yarn 或 pnpm install）。

从源码开发/调试

• 安装依赖：npm install
• 链接到全局（可选）：npm run link，之后可直接使用 plugnix-cli 命令
• 查看帮助：node bin/plugnix-cli.js --help
• 在本地测试：
  • 初始化：node bin/plugnix-cli.js init my-admin
  • 添加插件：cd my-admin && node ../bin/plugnix-cli.js add dashboard
• 日志：使用 --verbose 获取更多细节。

许可证

• 本项目使用 WTFPL 许可证。

语言与 i18n

• 工具会根据当前环境自动检测语言。用户也可以自行控制，按照以下规则。
• 语言检测优先级：-l 或 --lang 命令行参数 > 环境变量 PLUGNIX_LANG > 操作系统语言（使用 os-locale 检测）> 默认英文。
• 支持的语言代码：zh（中文）、en（英文）。
• 帮助文本与运行时提示都会根据当前语言显示；示例：
  • 英文帮助：plugnix-cli --lang en --help
  • 中文帮助（自动或强制）：plugnix-cli --lang zh --help
  • 运行时也可强制语言：plugnix-cli --lang en add dashboard
• 环境变量覆盖示例：
  • Windows PowerShell：$env:PLUGNIX_LANG = "en"; plugnix-cli --help
  • Bash：PLUGNIX_LANG=en plugnix-cli --help