@astryx-vue/cli 0.4.1 → 0.4.3

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# 维护 `@astryx-vue/cli`
+
+这个文件只写给改这个包的人。使用说明在文档站的 `/guide/cli`，包里没有第二份。
+
+## 文本从哪来
+
+CLI 不另存一份组件文档。`scripts/generate-catalog.mjs` 读：
+
+- `apps/docs/components/demos/*/meta.ts`：名字、分组和顺序
+- `apps/docs/docs/{en,zh}/components/<slug>/`：用法、props、插槽、事件和示例标题
+- `apps/docs/components/demos/<slug>/*.vue`：那些页面指向的示例源码
+- `apps/docs/components/demo-infra/reference/*.json`：anatomy 和无障碍信息
+- `apps/docs/docs/{en,zh}/guide` 和 `themes`：搜索主题和正文，以及 `theme` 用的主题记录、`init` 用的安装命令和代码片段
+- `apps/docs/docs/{en,zh}/guide/migration.md`：`upgrade` 打印的升级小节，和它去源码里找的旧名字
+- `apps/docs/components/playground/pages/*.vue`：模板源码；`templateManifest.ts`：模板标题和分类
+- 每个 `packages/*/package.json`：判断组件属于哪个包、版本和说明
+
+模板的说明和关键词是手写的，在 `packages/cli/src/generate/template-meta/`，每类模板一个文件，由 `template-meta.ts` 合并。它们属于源数据，不是生成物。
+
+示例的标题和说明按语言各存一份，代码两种语言只存一份。两个页面指向同一个 `.vue` 文件；如果一个页面改了代码、另一个没改，生成时直接报错并指出是哪个组件的第几个示例。
+
+结果提交在 `packages/cli/src/generated/catalog.json`。
+
+## 改完文档或模板之后
+
+```sh
+pnpm --filter @astryx-vue/cli generate
+```
+
+`pnpm check` 会跑 `generate:check`。它在这些情况下失败：`catalog.json` 过期、某个包里有 PascalCase 导出没有任何组件文档引用、某个演练场页面在 `template-meta.ts` 里没有元数据。`./icons`、`./locale`、CSS 和包根不算组件导出。
+
+只要 catalog 变了就要有 CLI 的 changeset，否则 npm 上的用户拿到的还是旧目录；`scripts/check-cli-catalog-release.mjs` 会在 PR 里拦住漏发。
+
+## 在本仓库里直接跑
+
+```sh
+pnpm --filter @astryx-vue/cli build
+node packages/cli/bin/astryx-vue.mjs component Button
+node packages/cli/bin/astryx-vue.mjs composable useClipboard
+node packages/cli/bin/astryx-vue.mjs docs guide/dark-mode --dense
+node packages/cli/bin/astryx-vue.mjs template --list
+node packages/cli/bin/astryx-vue.mjs template login-card --skeleton
+node packages/cli/bin/astryx-vue.mjs build "登录页"
+node packages/cli/bin/astryx-vue.mjs search login --type template
+node packages/cli/bin/astryx-vue.mjs manifest --json
+```
+
+## 相关包
+
+| 包 | 是什么 |
+| --- | --- |
+| `@astryx-vue/core` | 这个 CLI 记录的那些 Vue 组件 |
+| `@astryx-vue/themes` | Neutral、Butter、Chocolate、Gothic、Matcha、Stone、Y2K |

package/README.md

@@ -71,177 +71,25 @@ Global flags:
 | `--zh` | Simplified Chinese where the docs have a translation. |
 | `--cwd <dir>` | Project directory. Defaults to the working directory; `template` and `init` write inside it, and `upgrade`/`doctor` read it. |
 
-A composable takes `useClipboard` or `use-clipboard`. `component useClipboard` still prints it, and adds a line that points at the `composable` command. `component --list` lists components only. `search --type` accepts `component`, `composable`, `doc`, or `template`; composable hits carry `domain: "composable"` and a `command` that points at `composable <Name>`. A query that hits a name outranks one that only hits page text. Each result names the package it comes from, ranked by score and then, when scores tie, by domain (component, composable, doc, template) and name, so the order never moves between runs.
 
-`docs` takes a topic id, the same id with `themes/` instead of `theme/`, or a bare name that matches one topic, such as `dark-mode`. `--json` returns `docs.list` or `docs.detail`, and `docs.detail` includes the page `body`. `--depth 2` keeps `#` and `##` and drops every deeper heading with the body under it, which is how a long page stays readable; `headings` in the JSON lists only the headings that survived, and `depth` says what was asked for.
+## Docs
 
-## Themes
+The full command reference — JSON envelopes, error codes, template rules, `init` block rules, and the maintainer steps — lives on the docs site: <https://astryx-vue.pages.dev/en/guide/cli>. The site is the only copy of that text; this README stays short on purpose.
 
-`theme` lists the seven shipped themes with their own one-sentence summaries. `theme <name>` prints the four steps that load one: the stylesheet import, the `data-astryx-theme` attribute, how switching or running two side by side works, and how to verify. The steps come from the theme's own docs page and the themes index page; the command writes nothing.
+## Programmatic use
 
-A theme slug or its display name both resolve, so `theme butter` and `theme Butter` are the same request. `--json` returns `theme.list` or `theme.detail`, and `theme.detail` carries the whole docs page as `body` for an agent that wants the long version.
+```ts
+import { assertResponse, runCli } from '@astryx-vue/cli'
 
-## Upgrading
-
-`upgrade` reads the `@astryx-vue/core` version from the project's `package.json` and compares it with the version this CLI was generated from. It never asks the network.
-
-- Older: it prints every section of the upgrade guide — what changed, how it was written before, how it is written now, what to do — then looks through the project's own sources for the old names the guide replaces, and lists file and line. A theme target name only counts as an object key (`progressbar: {`), because the same word is also an HTML tag; a property or option name counts as a word, in camelCase or kebab-case.
-- Current: it says nothing needs doing and prints the changelog link.
-- Not installed, or a range it cannot read as a version: it says that, and either names the install command for the project's package manager or prints every form.
-
-Both lists come from `apps/docs/docs/{en,zh}/guide/migration.md`: the sections are the page's `###` sections, and the old names are the names its section titles and its `Removed | Use instead` table state.
-
-## Doctor
-
-`doctor` reports five checks and changes nothing:
-
-| Check | Fails or warns when |
-| --- | --- |
-| `core-version` | `@astryx-vue/core` is missing (fail), its range cannot be read as a version, or it is older or newer than this CLI's catalog (warn) |
-| `themes-installed` | `@astryx-vue/themes` is not a dependency (fail) |
-| `vue-version` | `vue` is missing (fail) or below 3.5.0 (warn) |
-| `theme-stylesheet` | No `@astryx-vue/themes/*.css` import is found (fail), or the file name is not one of the built-in themes (warn) |
-| `theme-attribute` | No `data-astryx-theme` is found (warn; Neutral works without it) |
-
-Exit code is `0` when every check passed or only warned, and `1` when one failed; the text still prints, and `--json` returns `doctor.report`. Sources are read from the project directory, skipping `node_modules`, build output, and hidden directories.
-
-## Templates
-
-`template --list` prints all 57 playground pages. `--type page` is the only kind today; `--type block` answers with a note instead of an error.
-
-Every template carries a hand-written one-sentence description and a keyword list in English and Chinese, in `src/generate/template-meta/` (one file per template category). The component list is extracted from the page's `@astryx-vue/core` imports, so it cannot drift from the source. Each record also carries `dependencies`, the npm packages the page imports; a ready page names only `vue` and `@astryx-vue/core`, and the catalog generator fails when a ready page pulls in anything else. That is why `template --list`, `template <slug>`, and their `--json` forms can say exactly what a copied page needs.
-
-Some pages import a package a project cannot install: five use `@astryx-vue/playground-charts`, a path alias that only exists inside the docs playground. Those are marked `isReady: false` with the reason. A page is ready when every non-relative import it really performs is `vue` or `@astryx-vue/core`; text inside a code sample the page displays, such as `@astryxdesign/core`, is page content and does not count. `--list` and `template <slug>` still show them; copying is refused with `ERR_TEMPLATE_NOT_READY`.
-
-`template <slug> <path>` writes one file:
-
-- a path that ends in a file name, or that already names a file, is the target file;
-- anything else is a directory and receives `<PascalCaseSlug>.vue`;
-- an existing file is only replaced with `--overwrite` (or `-f`), otherwise `ERR_FILE_EXISTS`;
-- a path outside the project directory is refused with `ERR_PATH_TRAVERSAL`.
-
-Copying rewrites the playground's `/template-assets/…` photo paths to an inline grey placeholder and reports how many it replaced, so the file renders without the docs site. It does not copy any asset and does not install anything: it names the packages the project's `package.json` does not list, plus an install command with the lockfile's package manager.
-
-`--skeleton` prints the component tags with layout attributes only: `gap`, `padding`, `width`, `maxWidth`, `height`, `columns`, `axis`, `justify`, `align`, `density`, `variant`, `hasDivider`, and the `rowGap`/`columnGap`/`contentPadding`/`minHeight` variants. Text, bindings other than layout, event handlers, and native HTML wrappers are dropped, so a page positioned with plain `<div>` reads flatter than it renders. The skeleton is a structure reference, not a compilable file.
-
-## Build
-
-`build "<idea>"` ranks the templates locally: field-weighted keyword matching over slug, title, description, keywords, and the components a page uses, with rare words counting more than common ones. No network, no model, same answer every run. Chinese is matched by character pairs, so no spaces are needed.
-
-- `TEMPLATE` is the closest page. `OTHER TEMPLATES` is the next two. A page that cannot be copied keeps its place only when it answers the idea clearly better, and it is marked with the reason.
-- `COMPONENTS` (up to 6) and `COMPOSABLES` (up to 4) come from the same ranking `search` uses, so the two commands cannot disagree. When the idea names fewer pieces than the limit, the recommended page's own components fill the rest, marked as such.
-- A weak match is dropped rather than padded. An idea nothing matches returns no template and says so.
-- `build` with no idea prints the workflow: find a template, copy it, then look up each component before writing code.
-
-## JSON envelopes
-
-Success responses are `{ apiVersion: 1, type, data }`. `template`, `build`, and `docs` responses carry `package` for where the records come from (`@astryx-vue/cli` for templates, `@astryx-vue/docs` for pages). Every template entry of `template.list`, `template.show`, and `template.skeleton` carries its own `dependencies` array next to `components`. `component.detail` and `composable.detail` carry the owning package, and every entry of `component.list` and `composable.list` carries its own, because one list can span packages.
-
-| Type | Command |
-| --- | --- |
-| `template.list`, `template.show`, `template.skeleton`, `template.copy` | `template` |
-| `build.help`, `build.kit` | `build` |
-| `component.list`, `component.detail` | `component` |
-| `composable.list`, `composable.detail` | `composable` |
-| `docs.list`, `docs.detail` | `docs` |
-| `search` | `search` |
-| `manifest` | `manifest` |
-| `theme.list`, `theme.detail` | `theme` |
-| `upgrade.report` | `upgrade` |
-| `doctor.report` | `doctor` |
-| `init.run` | `init` |
-| `help`, `version` | `--help`, `--version`, or no arguments with `--json` |
-
-Exit codes are `0` for success, `1` when the command ran but failed, and `2` for invalid usage. Branch on `code` in the JSON envelope, not on the message text.
-
-| Code | When |
-| --- | --- |
-| `ERR_UNKNOWN_TEMPLATE` | No template matches the slug. Up to five close slugs come back as suggestions. |
-| `ERR_TEMPLATE_NOT_READY` | The template imports a package the project cannot install. |
-| `ERR_FILE_EXISTS` | The target file exists and `--overwrite` was not passed. |
-| `ERR_PATH_TRAVERSAL` | A target path resolves outside the project directory. |
-| `ERR_INVALID_ARGUMENT` | Two modes were combined, a value is outside its choices, or the idea is blank. |
-| `ERR_UNKNOWN_COMPONENT`, `ERR_UNKNOWN_COMPOSABLE`, `ERR_UNKNOWN_TOPIC` | No record matches the name. |
-| `ERR_UNKNOWN_AGENT` | `--agent` is not `cursor`, `claude`, `codex`, `hermes`, or `all`. |
-| `ERR_UNKNOWN_FEATURE` | `--features` names something other than `agents`. |
-| `ERR_UNKNOWN_THEME` | No theme has that slug or display name. |
-
-`manifest --json` carries the same list per command, so an agent can read the codes without this table.
-
-## Agent block
-
-`init` prints the setup guide — which packages to install (canary ones with `@canary`, once they are on npm), the theme import, the locale snippet, and what to verify — and writes this managed block:
-
-```html
-<!-- Maintained by astryx-vue, do not edit manually -->
-...
-<!-- astryx-vue block end -->
-```
-
-If the file is missing, the command creates it. If the markers are already there, every run replaces only the block with freshly generated text. Other text stays. If the file exists without the markers, the block is appended. A second run still rewrites the block; it does not skip because the markers are already present. When the generated text matches, the bytes stay the same.
-
-The block names every package the catalog covers. A package npm does not serve yet (a `private` one) is still named, but with a note and no install command, so nobody is sent to a 404; a published canary package would get the `@canary` specifier. Then it teaches the three-step workflow (`build` to pick a page, `template` to copy it, `component`/`composable`/`docs` before writing code), lists the lookup commands, and says how to run the binary. It does not paste the component catalog.
-
-The install command in the guide follows the project: the `packageManager` field first, then `pnpm-lock.yaml`, `yarn.lock`, `bun.lock(b)`, or `package-lock.json`. With neither, all four forms are listed. `--features` is optional now; passing `agents` is the same as leaving it out, and any other feature is `ERR_UNKNOWN_FEATURE`.
-
-Where it writes:
-
-- no `--agent`: the first agent file the project already has, in the order `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.hermes.md`, `HERMES.md`; `AGENTS.md` when none exists;
-- `--agent cursor` or `--agent codex`: `AGENTS.md`;
-- `--agent claude`: `CLAUDE.md`;
-- `--agent hermes`: `.hermes.md`, or `HERMES.md` when the project already has that file;
-- `--agent all`: every known file that exists, or `AGENTS.md` when none does;
-- `--agent-docs-path <file>`: exactly that file, relative to the project directory. Missing directories are created; a path outside the project is refused with `ERR_PATH_TRAVERSAL`.
-
-## Where the text comes from
-
-The CLI does not keep a second copy of the component docs. `packages/cli/scripts/generate-catalog.mjs` reads:
-
-- `apps/docs/components/demos/*/meta.ts` for names, groups, and order
-- `apps/docs/docs/{en,zh}/components/<slug>/` for usage, props, slots, events, and example titles
-- `apps/docs/components/demos/<slug>/*.vue` for the example source those pages point at
-- `apps/docs/components/demo-infra/reference/*.json` for anatomy and accessibility
-- `apps/docs/docs/{en,zh}/guide` and `themes` for search topics, topic bodies, and the theme records (`theme`), plus the install commands and snippets `init` prints
-- `apps/docs/docs/{en,zh}/guide/migration.md` for the upgrade guide's sections and the old names `upgrade` searches for
-- `apps/docs/components/playground/pages/*.vue` for the template sources, and `templateManifest.ts` for their titles and categories
-- every `packages/*/package.json` for which package owns a component, and its exports when a page does not show an import
-
-The template descriptions and keywords are hand-written in `packages/cli/src/generate/template-meta/`, one file per template category, and merged by `template-meta.ts`. They are source data, not a generated file.
-
-Example titles and descriptions are kept once per language, but the example code is stored once for both: both pages point at the same `.vue` file. The generator stops with an error naming the component and the example number if the two pages ever show different code, so one language cannot silently borrow the other's snippet. `examplesFor()` in `packages/cli/src/catalog.ts` is the only place that picks a language back out.
-
-The result is committed at `packages/cli/src/generated/catalog.json`. `pnpm --filter @astryx-vue/cli build` regenerates it and bundles it into `dist`, which is what the published tarball runs. After a docs or template change, regenerate it and commit the diff:
-
-```sh
-pnpm --filter @astryx-vue/cli generate
+const result = await runCli(['search', 'dialog', '--json'], { cwd: process.cwd() })
+const found = assertResponse(result.stdout, 'search')
 ```
 
-`pnpm check` runs `generate:check`. That fails when `catalog.json` is stale, when a PascalCase export of any package is not imported by a documented component, and when a playground page has no metadata in `template-meta.ts`. `./icons`, `./locale`, CSS, and the package root are not component exports.
-
-`catalog.packages` lists every package the catalog covers (`core`, `themes`, `richtext`, `charts`, `lab`) with its directory, whether it publishes only under the `canary` tag, and whether it is `published`. `published` is false for a `private` package: npm has no version of it, so no output prints an install command for it. A component's `package` is the one that exports it by subpath, else the one that has a source entry for it.
-
-`swizzle`, `discover`, `gap-report`, `integration`, and `blog` are not part of this package, and there is no MCP server. `theme`, `upgrade`, and `doctor` print guidance and reports; none of them edits a project file.
+`runCli` takes the same arguments as the binary and returns `{ exitCode, stdout, stderr }`. `assertResponse` narrows the envelope to the type you expect.
 
-## Related packages
+## Contributing
 
-| Package | What it is |
-| --- | --- |
-| `@astryx-vue/core` | The Vue components this CLI documents |
-| `@astryx-vue/themes` | Neutral, Butter, Chocolate, Gothic, Matcha, Stone, and Y2K |
-
-## Try it in this repo
-
-```sh
-pnpm --filter @astryx-vue/cli build
-node packages/cli/bin/astryx-vue.mjs component Button
-node packages/cli/bin/astryx-vue.mjs composable useClipboard
-node packages/cli/bin/astryx-vue.mjs docs guide/dark-mode --dense
-node packages/cli/bin/astryx-vue.mjs template --list
-node packages/cli/bin/astryx-vue.mjs template login-card --skeleton
-node packages/cli/bin/astryx-vue.mjs build "login page with SSO"
-node packages/cli/bin/astryx-vue.mjs search login --type template
-node packages/cli/bin/astryx-vue.mjs manifest --json
-```
+Where the text comes from, how to regenerate the catalog, and how to run the command from a checkout are in [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 

package/README.zh-CN.md

@@ -71,176 +71,25 @@ npm run astryx-vue -- component Button
 | `--zh` | 文档有中文版时用简体中文。 |
 | `--cwd <dir>` | 项目目录，默认当前工作目录；`template` 和 `init` 只往这里面写，`upgrade` 和 `doctor` 只在这里读。 |
 
-组合式函数可写 `useClipboard` 或 `use-clipboard`。`component useClipboard` 也能查到，并多印一行指向 `composable` 命令。`component --list` 只列组件。`search --type` 接受 `component`、`composable`、`doc`、`template`；组合式函数命中的结果是 `domain: "composable"`，`command` 指向 `composable <Name>`。命中名字的结果排在只命中正文的结果前面。每条结果都标出来自哪个包；分数相同时按领域（组件、组合式函数、文档、模板）再按名字排序，跑两次顺序不会变。
 
-`docs` 接受主题 id、把 `theme/` 换成 `themes/` 的写法，或能唯一匹配某个主题的裸名，例如 `dark-mode`。`--json` 返回 `docs.list` 或 `docs.detail`，`docs.detail` 里有整页 `body`。`--depth 2` 只留 `#` 和 `##`，更深的标题连同它下面的正文一起省掉，长页面因此读得下去；JSON 里的 `headings` 只列还在正文里的标题，`depth` 说明调用方要的是第几层。
+## 完整文档
 
-## 主题
+命令的完整说明——JSON 信封、错误码、模板规则、`init` 区块规则、维护者步骤——都在文档站：<https://astryx-vue.pages.dev/guide/cli>。这份正文只在文档站维护，包里的 README 故意保持简短。
 
-`theme` 列出内置的 7 套主题，每套带文档页自己的那句说明。`theme <名字>` 输出接入四步：引哪个样式表、`data-astryx-theme` 写什么、怎么换主题或同时用两套、改完怎么验证。这些文字来自主题自己的文档页和主题索引页，命令不写任何文件。
+## 在代码里调用
 
-slug 和显示名都能用，`theme butter` 和 `theme Butter` 是同一个请求。`--json` 返回 `theme.list` 或 `theme.detail`，`theme.detail` 里带整页 `body`，供想要长文的助手读。
+```ts
+import { assertResponse, runCli } from '@astryx-vue/cli'
 
-## 升级
-
-`upgrade` 读项目 `package.json` 里 `@astryx-vue/core` 的版本，和这个 CLI 生成时对应的版本比，不联网。
-
-- 比 CLI 旧：打印升级指南的每一节（变了什么、以前怎么写、现在怎么写、怎么改），再在项目自己的源码里找出指南里被替换掉的旧名字，列出文件和行号。主题挂点名只认对象键（`progressbar: {`），因为同一个词也是 HTML 标签；属性和选项名按单词认，camelCase 和 kebab-case 都算。
-- 已经一样：说明不用升级，并给出更新日志链接。
-- 没装，或版本写法读不出来：说明情况，并按项目包管理器给出安装命令（读不出包管理器就列全部写法）。
-
-这两份内容都来自 `apps/docs/docs/{en,zh}/guide/migration.md`：小节就是页面的 `###` 小节，旧名字来自小节标题和页面里 `Removed | Use instead` 表格。
-
-## 体检
-
-`doctor` 报告五项检查，不改任何文件：
-
-| 检查 | 什么时候失败或提醒 |
-| --- | --- |
-| `core-version` | 没装 `@astryx-vue/core`（失败）；版本写法读不出来，或比 CLI 的 catalog 旧/新（提醒） |
-| `themes-installed` | 没有依赖 `@astryx-vue/themes`（失败） |
-| `vue-version` | 没装 `vue`（失败）或低于 3.5.0（提醒） |
-| `theme-stylesheet` | 没找到任何 `@astryx-vue/themes/*.css` 引入（失败），或文件名不是内置主题（提醒） |
-| `theme-attribute` | 没找到 `data-astryx-theme`（提醒；Neutral 不写也能用） |
-
-全部通过或只有提醒时退出码是 `0`，有失败时是 `1`，文本照样打印；`--json` 返回 `doctor.report`。只读项目目录里的源码，跳过 `node_modules`、构建产物和隐藏目录。
-
-## 模板
-
-`template --list` 列出全部 57 个演练场页面。目前 `--type` 只有 `page` 一种；`--type block` 会给一句说明，不报错。
-
-每个模板都有一句手写说明和中英两套关键词，放在 `src/generate/template-meta/`，每类模板一个文件。组件清单从页面里 `@astryx-vue/core` 的 import 自动提取，不会和源码脱节。每条记录还带 `dependencies`：这个页面 import 了哪些 npm 包。可复制的模板只会有 `vue` 和 `@astryx-vue/core`，可复制模板若多引一个包，生成 catalog 时直接报错。所以 `template --list`、`template <slug>` 和它们的 `--json` 都能直接说清落地要装什么。
-
-有些页面引用了用户项目装不上的包：5 个用 `@astryx-vue/playground-charts`（只存在于文档站演练场的路径别名）。这些标为 `isReady: false` 并写明原因。判断标准是页面真正执行的导入：只要非相对导入都是 `vue` 或 `@astryx-vue/core` 就算可复制；页面里展示的示例代码文本（例如 `@astryxdesign/core`）属于页面内容，不算导入。`--list` 和 `template <slug>` 照样能看，复制会被拒绝，报 `ERR_TEMPLATE_NOT_READY`。
-
-`template <slug> <path>` 只写一个文件：
-
-- 以文件名结尾的路径，或本身就指向一个文件的路径，就写这个文件；
-- 其余都当作目录，写入 `<PascalCaseSlug>.vue`；
-- 已存在的文件要加 `--overwrite`（或 `-f`）才覆盖，否则报 `ERR_FILE_EXISTS`；
-- 越出项目目录的路径报 `ERR_PATH_TRAVERSAL`。
-
-复制时会把演练场的 `/template-assets/…` 图片地址换成一个内联的灰色占位图，并报告替换了多少处，这样文件不依赖文档站也能渲染。它不复制任何资源文件，也不安装任何东西：只列出项目 `package.json` 里没有的包，再按锁文件对应的包管理器给一条安装命令。
-
-`--skeleton` 只输出组件标签和布局属性：`gap`、`padding`、`width`、`maxWidth`、`height`、`columns`、`axis`、`justify`、`align`、`density`、`variant`、`hasDivider`，以及 `rowGap`/`columnGap`/`contentPadding`/`minHeight`。文字、布局以外的绑定、事件处理函数和原生 HTML 包裹层都会丢掉，所以用 `<div>` 定位置的页面看起来会比实际更平。骨架是结构参考，不是能直接编译的文件。
-
-## build
-
-`build "<想法>"` 在本地给模板打分：对 slug、标题、说明、关键词和页面用到的组件做字段加权关键词匹配，越少见的词权重越高。没有网络，没有模型，同一句话每次结果一样。中文按字符二元组匹配，不需要空格分词。
-
-- `TEMPLATE` 是最接近的页面，`OTHER TEMPLATES` 是接下来两个。不能复制的页面只有在明显更贴合时才排到前面，并标出原因。
-- `COMPONENTS`（最多 6 个）和 `COMPOSABLES`（最多 4 个）用的是 `search` 那套排序，两个命令不会互相矛盾。想法里点到的部件不够时，用推荐页面自己用到的组件补齐，并标出来源。
-- 命中太弱的直接丢掉，不凑数。完全没命中时不给模板，并说明这一点。
-- 不带想法时 `build` 打印工作流：先找模板，再复制，最后写代码前逐个查组件。
-
-## JSON 信封
-
-成功响应是 `{ apiVersion: 1, type, data }`。`template`、`build`、`docs` 的响应带 `package`，说明记录来自哪个包（模板是 `@astryx-vue/cli`，文档页是 `@astryx-vue/docs`）。`template.list`、`template.show`、`template.skeleton` 的每条模板记录在 `components` 旁边带 `dependencies`。`component.detail` 和 `composable.detail` 带所属的包；`component.list` 和 `composable.list` 的每一条各自带 `package`，因为一个列表可能横跨多个包。
-
-| 类型 | 命令 |
-| --- | --- |
-| `template.list`、`template.show`、`template.skeleton`、`template.copy` | `template` |
-| `build.help`、`build.kit` | `build` |
-| `component.list`、`component.detail` | `component` |
-| `composable.list`、`composable.detail` | `composable` |
-| `docs.list`、`docs.detail` | `docs` |
-| `search` | `search` |
-| `manifest` | `manifest` |
-| `theme.list`、`theme.detail` | `theme` |
-| `upgrade.report` | `upgrade` |
-| `doctor.report` | `doctor` |
-| `init.run` | `init` |
-| `help`、`version` | `--help`、`--version`，或带 `--json` 不带参数 |
-
-退出码：成功 `0`，命令跑了但没成功 `1`，用法错误 `2`。分支判断请用信封里的 `code`，不要匹配消息文本。
-
-| 错误码 | 什么时候出现 |
-| --- | --- |
-| `ERR_UNKNOWN_TEMPLATE` | 没有模板匹配这个 slug。会附带最多 5 个相近的 slug。 |
-| `ERR_TEMPLATE_NOT_READY` | 模板引用了项目装不上的包。 |
-| `ERR_FILE_EXISTS` | 目标文件已存在，且没加 `--overwrite`。 |
-| `ERR_PATH_TRAVERSAL` | 目标路径越出了项目目录。 |
-| `ERR_INVALID_ARGUMENT` | 两个模式混用、取值不在选项内，或想法是空白串。 |
-| `ERR_UNKNOWN_COMPONENT`、`ERR_UNKNOWN_COMPOSABLE`、`ERR_UNKNOWN_TOPIC` | 没有记录匹配这个名字。 |
-| `ERR_UNKNOWN_AGENT` | `--agent` 不是 `cursor`、`claude`、`codex`、`hermes` 或 `all`。 |
-| `ERR_UNKNOWN_FEATURE` | `--features` 写了 `agents` 以外的东西。 |
-
-`manifest --json` 按命令携带同一份错误码列表，agent 不用读这张表。
-
-## agent 区块
-
-`init` 先打印接入说明（装哪些包、canary 的带 `@canary`（前提是已经发到 npm）、主题样式引哪一行、语言怎么提供、改完怎么验证），再写入这个受管理区块：
-
-```html
-<!-- Maintained by astryx-vue, do not edit manually -->
-...
-<!-- astryx-vue block end -->
-```
-
-文件不存在就创建。已经有标记时，每次只替换区块内容，其余文字保持不动。文件存在但没有标记时，把区块追加到末尾。第二次运行仍然重写区块，不会因为标记已存在就跳过；生成内容一致时字节不变。
-
-区块开头列一遍 catalog 覆盖的包。npm 上还没有的包（仓库里标了 `private`）照样列名字，但会写明「还没发布到 npm」并且不给安装命令，免得有人照着敲一个 404；已经发布的 canary 包才会写成 `@canary`。然后写三步工作流（用 `build` 挑页面，用 `template` 复制，写代码前用 `component`/`composable`/`docs` 查），加上查询命令清单和怎么运行这个命令。它不会把组件目录贴进来。
-
-接入说明里的安装命令跟着项目走：先看 `packageManager` 字段，再看 `pnpm-lock.yaml`、`yarn.lock`、`bun.lock(b)`、`package-lock.json`。两样都没有就把四种写法都列出来。`--features` 现在是可选的，写 `agents` 和不写一样，写别的仍然是 `ERR_UNKNOWN_FEATURE`。
-
-写到哪里：
-
-- 不加 `--agent`：项目里已经有的第一个 agent 文件，顺序是 `AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.hermes.md`、`HERMES.md`；都没有就写 `AGENTS.md`；
-- `--agent cursor` 或 `--agent codex`：`AGENTS.md`；
-- `--agent claude`：`CLAUDE.md`；
-- `--agent hermes`：`.hermes.md`；项目里已有 `HERMES.md` 时写它；
-- `--agent all`：已经存在的全部已知文件；一个都没有就写 `AGENTS.md`；
-- `--agent-docs-path <file>`：就写这个文件，相对项目目录解析。缺的目录会自动创建，越出项目目录报 `ERR_PATH_TRAVERSAL`。
-
-## 文本从哪来
-
-CLI 不另存一份组件文档。`packages/cli/scripts/generate-catalog.mjs` 读：
-
-- `apps/docs/components/demos/*/meta.ts`：名字、分组和顺序
-- `apps/docs/docs/{en,zh}/components/<slug>/`：用法、props、插槽、事件和示例标题
-- `apps/docs/components/demos/<slug>/*.vue`：那些页面指向的示例源码
-- `apps/docs/components/demo-infra/reference/*.json`：anatomy 和无障碍信息
-- `apps/docs/docs/{en,zh}/guide` 和 `themes`：搜索主题和正文，以及 `theme` 用的主题记录、`init` 用的安装命令和代码片段
-- `apps/docs/docs/{en,zh}/guide/migration.md`：`upgrade` 打印的升级小节，和它去源码里找的旧名字
-- `apps/docs/components/playground/pages/*.vue`：模板源码；`templateManifest.ts`：模板标题和分类
-- 每个 `packages/*/package.json`：判断组件属于哪个包、版本和说明（`upgrade`/`doctor`/`init` 用）；页面里没写 import 时用它的 exports 推断
-
-模板的说明和关键词是手写的，在 `packages/cli/src/generate/template-meta/`，每类模板一个文件，由 `template-meta.ts` 合并，属于源数据，不是生成物。
-
-示例的标题和说明按语言各存一份，但示例代码两种语言只存一份：两个页面指向的是同一个 `.vue` 文件。以后要是一个页面改了代码、另一个没改，生成时直接报错并指出是哪个组件的第几个示例，不会让一种语言悄悄用上另一种的代码。取回某种语言的示例只走 `packages/cli/src/catalog.ts` 里的 `examplesFor()`。
-
-结果提交在 `packages/cli/src/generated/catalog.json`。`pnpm --filter @astryx-vue/cli build` 会重新生成并打进 `dist`，也就是 npm 包实际运行的那份。文档或模板改过之后，重新生成并提交 diff：
-
-```sh
-pnpm --filter @astryx-vue/cli generate
+const result = await runCli(['search', 'dialog', '--json'], { cwd: process.cwd() })
+const found = assertResponse(result.stdout, 'search')
 ```
 
-`pnpm check` 会跑 `generate:check`。它会在这几种情况下失败：`catalog.json` 过期、某个包里有 PascalCase 导出没有任何组件文档引用、或者某个演练场页面在 `template-meta.ts` 里没有元数据。`./icons`、`./locale`、CSS 和包根不算组件导出。
-
-`catalog.packages` 列出 catalog 覆盖的每个包（`core`、`themes`、`richtext`、`charts`、`lab`），带目录、「是否只发 canary」的标记，以及 `published`。`private` 的包 `published` 是 false：npm 上没有它的版本，所以任何输出都不会给它写安装命令。组件的 `package` 取「有它这个子路径导出的包」，没有就取「`src/` 里有它这个目录的包」。
+`runCli` 收的参数和命令行一致，返回 `{ exitCode, stdout, stderr }`。`assertResponse` 按你要的类型校验信封。
 
-`swizzle`、`discover`、`gap-report`、`integration`、`blog` 不在这个包里，也没有 MCP 服务。`theme`、`upgrade`、`doctor` 只输出指引和报告，都不改项目文件。
+## 参与开发
 
-## 相关包
-
-| 包 | 是什么 |
-| --- | --- |
-| `@astryx-vue/core` | 这个 CLI 记录的那些 Vue 组件 |
-| `@astryx-vue/themes` | Neutral、Butter、Chocolate、Gothic、Matcha、Stone、Y2K |
-
-## 在本仓库里试
-
-```sh
-pnpm --filter @astryx-vue/cli build
-node packages/cli/bin/astryx-vue.mjs component Button
-node packages/cli/bin/astryx-vue.mjs composable useClipboard
-node packages/cli/bin/astryx-vue.mjs docs guide/dark-mode --dense
-node packages/cli/bin/astryx-vue.mjs template --list
-node packages/cli/bin/astryx-vue.mjs template login-card --skeleton
-node packages/cli/bin/astryx-vue.mjs build "登录页"
-node packages/cli/bin/astryx-vue.mjs search login --type template
-node packages/cli/bin/astryx-vue.mjs manifest --json
-```
+文本从哪来、怎么重新生成目录、怎么在本仓库里直接跑这个命令，见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 ## 许可