@vetta-org/plugin-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@vetta-org/plugin-cli` are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Added `vetta-plugin-cli init --id <plugin-id>`: scaffolds a buildable plugin project together with an `AGENTS.md` brief, so any coding agent can bootstrap in an unfamiliar directory without host-side knowledge. Inside a marketplace hub (`.vetta/marketplace.json`) the new plugin is also listed there, with a repository-relative `source.path`.
+- Added `vetta-plugin-cli docs`: prints the absolute path of the manual shipped inside the installed `@vetta-org/plugin-sdk`, plus the SDK version it documents and the plugin/hub the command resolved. Nobody has to hard-code a `node_modules` path that workspace hoisting can move.
+- Added `vetta-plugin-cli init hub`: scaffolds a conformant ability marketplace repository — index skeleton, `abilities/{plugins,mcp,skills,scenes}/`, a repository-level `AGENTS.md`, and a CI workflow that runs `sync --check`.
+- Added `vetta-plugin-cli sync` (and `--check` for CI): reconciles a marketplace repository's `.vetta/marketplace.json` against each ability directory — version, api version, permissions and commands are pulled from the packages, missing build output and slug mismatches are reported, and `marketplaceVersion` is advanced so clients actually pick the update up. Ability directories that are not listed are reported, never added. `docs` and `add .` now point at it the moment it becomes relevant.
+- Added `vetta-plugin-cli uninstall [plugin-id]`: removes a plugin through the Desktop approval path, inferring the target from the current directory when no id is given.
+- Added `vetta-plugin-cli watch` (and `--stop`): asks the running Desktop to load the nearest plugin from its project directory, so source edits take effect without a build → pack → install round trip.
+- `add` now accepts a plugin project directory (`add .`) and resolves the archive that project packed, instead of treating the directory as an archive path.
+
+- Added `npx @vetta-org/plugin-cli add <npm-package>` with script-free npm resolution, package-envelope validation, archive integrity binding, and installation through the running Vetta Desktop Action RPC.
+- Added `vetta-plugin-cli reload <plugin-id>` so pending plugin updates can be applied through the Desktop approval and lifecycle path.

package/README.md

@@ -0,0 +1,108 @@
+# @vetta-org/plugin-cli
+
+Create, document and install Vetta Desktop plugins from any directory.
+
+## Start a plugin
+
+```bash
+npx @vetta-org/plugin-cli init --id my-plugin --name "My Plugin"
+cd my-plugin && npm install
+npm run install:vetta      # build → pack → install into the running Desktop
+```
+
+The scaffold includes an `AGENTS.md` brief so a coding agent can pick the project up without any
+host-side setup. Inside a marketplace hub (a repository with `.vetta/marketplace.json`) the new
+plugin is also listed in that manifest.
+
+## Remove a plugin
+
+```bash
+npx @vetta-org/plugin-cli uninstall            # the plugin in this directory
+npx @vetta-org/plugin-cli uninstall some-id    # by id, from anywhere
+```
+
+## Start a marketplace
+
+```bash
+npx @vetta-org/plugin-cli init hub \
+  --name my-market \
+  --repository https://github.com/me/my-market \
+  --min-app-version 0.55.0
+```
+
+Creates the index skeleton, the `abilities/` layout, a repository-level `AGENTS.md`, and a CI
+workflow running `sync --check`. Add abilities with `init` inside `abilities/plugins/<slug>`.
+
+## Keep a marketplace repository honest
+
+```bash
+npx @vetta-org/plugin-cli sync           # reconcile .vetta/marketplace.json with the ability directories
+npx @vetta-org/plugin-cli sync --check   # report only, non-zero exit — for CI
+```
+
+The index carries data that is derived from each ability package, under constraints that bite
+remotely: the host refuses to sync an entry whose version differs from the package, it will not
+install a plugin whose built entry is missing from the published directory, and clients silently
+skip an update when `marketplaceVersion` did not change. `sync` reconciles all three.
+
+## Find the manual
+
+```bash
+npx @vetta-org/plugin-cli docs
+```
+
+Prints where the manual bundled with the installed `@vetta-org/plugin-sdk` lives, which SDK version
+it documents, and which plugin (and hub) the current directory belongs to. The manual is always the
+one this project compiles against, so it never describes contracts the user's host lacks.
+
+## Install a plugin
+
+Install an npm-distributed plugin into the running Vetta Desktop app:
+
+```bash
+npx @vetta-org/plugin-cli add @example/vetta-plugin-demo
+```
+
+The npm package is fetched with lifecycle scripts disabled. The CLI extracts only the archive declared by
+`package.json#vetta`, then asks the running Desktop host to validate, approve, and install it. It never writes
+`~/.vetta/plugins` directly.
+
+Local archives and HTTP(S) archives use the same command:
+
+```bash
+npx @vetta-org/plugin-cli add ./release/demo-1.0.0.zip
+npx @vetta-org/plugin-cli add https://example.com/demo-1.0.0.zip
+```
+
+When an update is installed as a pending version, apply it through the running Desktop host instead of
+restarting or editing the plugin store directly:
+
+```bash
+npx @vetta-org/plugin-cli reload demo
+```
+
+Reload follows the same Desktop approval flow as the UI and reports the active version after approval.
+
+Use `--json` for machine-readable output. Set `VETTA_CONFIG_DIR` or `VETTA_HOME` when targeting an isolated
+Desktop environment.
+
+## Publisher contract
+
+The published plugin package must include a standard Desktop plugin archive and declare it in `package.json`:
+
+```json
+{
+  "name": "@example/vetta-plugin-demo",
+  "version": "1.0.0",
+  "files": ["release/vetta-plugin.zip"],
+  "vetta": {
+    "schemaVersion": 1,
+    "type": "desktop-plugin",
+    "pluginId": "demo",
+    "archive": "release/vetta-plugin.zip"
+  }
+}
+```
+
+`@vetta-org/plugin-vite` can create both the versioned archive and this stable npm archive with
+`package: { npmArchive: true }`.

package/dist/agents-template.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 随脚手架落地的 Agent 说明书。
+ *
+ * 它替代的是「把开发知识写死在工作台插件的 skill 里」那套做法：那份 skill 只有 Vetta
+ * 自己的 Agent 读得到，而且每加一个能力就要改一次、还要等 App 发版才到用户手里。这里
+ * 反过来——工程自带说明书，说明书只说「去哪读手册」，手册随 SDK 版本进 node_modules。
+ * 因此任何 Agent（Claude Code、Cursor、Vetta 自己）在任何陌生目录都能自举，而且读到的
+ * 永远是这个工程实际编译所针对的那份合同。
+ *
+ * 单位是插件目录本身：外面是能力市场仓库、是单插件仓库、还是一堆别的东西，都不影响这里。
+ */
+export declare function renderAgentsGuide(input: {
+    pluginId: string;
+    displayName: string;
+}): string;
+//# sourceMappingURL=agents-template.d.ts.map

package/dist/agents-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../src/agents-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CA8E1F","sourcesContent":["/**\n * 随脚手架落地的 Agent 说明书。\n *\n * 它替代的是「把开发知识写死在工作台插件的 skill 里」那套做法：那份 skill 只有 Vetta\n * 自己的 Agent 读得到，而且每加一个能力就要改一次、还要等 App 发版才到用户手里。这里\n * 反过来——工程自带说明书，说明书只说「去哪读手册」，手册随 SDK 版本进 node_modules。\n * 因此任何 Agent（Claude Code、Cursor、Vetta 自己）在任何陌生目录都能自举，而且读到的\n * 永远是这个工程实际编译所针对的那份合同。\n *\n * 单位是插件目录本身：外面是能力市场仓库、是单插件仓库、还是一堆别的东西，都不影响这里。\n */\nexport function renderAgentsGuide(input: { pluginId: string; displayName: string }): string {\n\treturn `# ${input.displayName}\n\nVetta 桌面插件工程。**先读手册再写代码**——不要凭记忆写 SDK API，这套合同变化很快。\n\n## 第一步：找到并阅读手册\n\n\\`\\`\\`bash\nnpx vetta-plugin-cli docs\n\\`\\`\\`\n\n它打印出随 \\`@vetta-org/plugin-sdk\\` 一起装进 \\`node_modules\\` 的手册目录**绝对路径**，以及\n这份手册对应的 SDK 版本。**不要硬编码这个路径**：工作区可能把依赖提升到仓库根，一仓多插件\n时各插件还可能钉不同的 SDK 版本。\n\n拿到路径后，用 read 工具按这个顺序打开：\n\n| 顺序 | 文件 | 何时读 |\n| --- | --- | --- |\n| 1 | \\`README.md\\` | 总是先读：能力矩阵、信任模型、导航 |\n| 2 | \\`getting-started.md\\` | 首次写代码、构建、安装调试 |\n| 3 | \\`manifest.md\\` | 写/改 \\`plugin.json\\`、贡献智能体与团队 |\n| 4 | \\`permissions.md\\` | 选定权限列表之前 |\n| 5 | 按扩展点选读 | \\`ui-slots.md\\` / \\`conversation-and-agent.md\\` / \\`message-cards.md\\` / \\`mcp.md\\` / \\`ai.md\\` / \\`browser.md\\` / \\`app-actions.md\\` |\n\n实现任一扩展点**之前**再读对应那章。手册是唯一真源，本文件与它冲突时以手册为准。\n\n## 开发闭环\n\n\\`\\`\\`bash\nnpm install\nnpm run dev            # Vite + Module Federation 开发服务器\nnpm run build          # 产出 dist/\nnpm run install:vetta  # 打包并装进正在运行的 Vetta（需要 Vetta 已启动）\nnpx vetta-plugin-cli watch   # 开热更新：宿主改从本工程目录加载，改完即生效\nnpx vetta-plugin-cli uninstall  # 卸载（省略 id 即本工程对应的插件）\n\\`\\`\\`\n\n\\`install:vetta\\` 走 \\`vetta-plugin-cli add .\\`：它找到本工程打出来的归档，交给正在运行的\nDesktop 校验、授权、安装。它**不会**直接写 \\`~/.vetta/plugins\\`。\n\n装完若提示有 pending 版本，用 \\`npx vetta-plugin-cli reload ${input.pluginId}\\` 让宿主应用它。\n\n开发期建议开热更新（\\`watch\\`）：之后改源码即时生效，不用每次重新打包安装。改 \\`plugin.json\\`\n的权限或命令声明时仍需重新安装一次，让宿主把授权落盘。\\`watch --stop\\` 关闭。\n\n## 如果这个目录之上有能力市场索引\n\n\\`vetta-plugin-cli docs\\` 会告诉你有没有（它会打印 \\`Marketplace index:\\`）。有的话，**改完\n\\`version\\` / \\`permissions\\` / \\`pluginApiVersion\\` 之后要回仓库根跑一次**：\n\n\\`\\`\\`bash\nnpx vetta-plugin-cli sync          # 从各能力目录回填索引，并推进 marketplaceVersion\nnpx vetta-plugin-cli sync --check  # 只报不写，CI 用\n\\`\\`\\`\n\n索引里的 \\`version\\` 与 \\`plugin.json\\` 的 \\`version\\` 必须**完全相等**，否则宿主同步直接失败；\n而内容变了却不换 \\`marketplaceVersion\\` 时，客户端既不报错也不更新——用户只是永远收不到。\n\\`add .\\` 装完若检测到索引还停在旧版本，会当场提醒你。\n\n## 不可违反的几条\n\n- **样式只用 Tailwind \\`className\\`**。禁止新建业务 CSS、禁止在 \\`style.css\\` 里写 \\`button\\`/\\`div\\`/\\`*\\`\n  这类选择器——插件与宿主共享同一个页面，全局选择器会污染整个 UI。\n- **可能失败的路径必须上报**：读文件、解析、网络、外部库的 catch 里调用\n  \\`ctx.ui.notify({ message, error })\\`（无需权限）。禁止只写死「失败」文案并丢掉原始 error。\n- **权限按需最小声明**。构建期会校验产物用到的能力与 \\`plugin.json\\` 的声明是否匹配，缺了直接\n  构建失败。但 UI 槽位不在这条校验里——那类缺权限在运行时只是静默跳过，所以对着手册核对。\n- **不要写 \\`agent_mode\\`**（已废弃，无运行时语义）。想收窄某个工具的使用场景，把「何时不该用它 +\n  替代做法」写进该工具 description 的反向触发段。\n- **顶层不要出现依赖共享 React 的 JSX**，放进组件或 \\`activate\\` 内（Module Federation 的加载时序）。\n- 依赖用 registry 上已发布的 semver，不要 \\`workspace:*\\`。\n- **\\`dist/\\` 要进版本库**。插件通过仓库目录分发时，宿主直接读 \\`plugin.json\\` 指向的 \\`entry\\`\n  与 \\`styles\\`，它不会替你构建——目录里没有构建产物就装不上。\n## 信息不足时\n\n插件 id、展示名、要用哪些权限、功能边界、是否立刻安装——**问用户**，不要自己假定。\n`;\n}\n"]}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\nimport { runPluginCli } from \"./command.js\";\n\nprocess.exitCode = await runPluginCli(process.argv.slice(2));\n"]}