create-vue-workspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 create-vue-workspace contributors
+
+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/README.md

@@ -0,0 +1,173 @@
+# create-vue-workspace
+
+一个可发布到 npm 的 CLI，用于生成 **Vue 3 + Vite + TypeScript 的 pnpm monorepo 工作区**，并以 Angular CLI 风格的 `new` + `generate` 命令持续生成代码。
+
+命令别名：`cvw`（对应 create-vue-workspace）
+
+## 命令模型
+
+对齐 Angular CLI 的两段式：`new` 建工作区，`generate` 跑生成器。
+
+```
+cvw new [name]                  # 创建工作区
+cvw generate <type> [name]      # 运行生成器，别名 cvw g
+```
+
+### 生成器
+
+| type | 别名 | 产物 | 关键选项 |
+| --- | --- | --- | --- |
+| `component` | `c` | `packages/<name>/` 独立组件包，并自动接线聚合包 | `--aggregator`（默认 `ui`）、`--with-sub`、`--skip-tests` |
+| `package` | `pkg` | `packages/<name>/` 通用包骨架 | `--vue`（附带 vue 依赖） |
+| `hook` | `h` | `<pkg>/src/composition/use-<name>.ts`，并追加 re-export | `--pkg`（默认 `hooks`） |
+| `view` | `v` | `apps/<app>/src/views/<name>.vue`，并自动注册路由 | `--app`（默认 `web`）、`--route`、`--skip-route` |
+| `util` | `u` | `<pkg>/src/<name>.ts`，并追加 re-export | `--pkg`（默认 `utils`） |
+| `app` | `a` / `application` | `apps/<name>/` 新应用，并维护根 scripts 与 changeset ignore | `--port`、`--template`（默认 `web`）、`--ui` |
+
+所有生成器通用：`--dry-run`（只打印将生成的文件，不落盘）、`-y/--yes`（非交互）。
+
+### 快速开始
+
+```bash
+# 创建工作区
+pnpm create vue-workspace my-app
+# 或
+npx create-vue-workspace@latest my-app
+
+cd my-app
+pnpm install
+pnpm dev
+
+# 生成代码
+cvw g c button            # 独立组件包，自动接线 packages/ui
+cvw g pkg hooks --vue     # 通用包
+cvw g h theme --pkg hooks # composable
+cvw g u array             # 工具函数模块
+cvw g v user/list         # 页面 + 自动注册路由
+cvw g app admin --port 5174
+```
+
+### `cvw new` 选项
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `--scope <@xxx>` | 生成物的包 scope | 由目录名推导，如 `@my-app` |
+| `--packages <list>` | 初始创建的 packages，逗号分隔 | `ui,utils` |
+| `--ui <farris\|none>` | 是否引入 `@farris/ui-vue` | `farris` |
+| `--port <port>` | 应用开发端口 | `5173` |
+| `--skip-install` | 跳过依赖安装 | — |
+| `--skip-git` | 跳过 git 初始化 | — |
+| `--dry-run` | 只打印将生成的文件，不落盘 | — |
+| `-y, --yes` | 全部使用默认值，非交互（适合 CI） | — |
+
+### 交互式
+
+省略参数时会像 Angular CLI 一样追问，`-y` 下则直接报错：
+
+```bash
+cvw g            # 追问：选择生成器
+cvw g c          # 追问：组件名称
+cvw new          # 追问：工程信息
+cvw g list       # 打印生成器清单
+```
+
+### 名称归一化
+
+输入 `Button` / `button` / `input_group` 都会被归一化：目录 `button`、组件名 `FButton`、选择器 `f-button`、文件 `button.component.tsx`。
+
+`cvw g h use-theme` 与 `cvw g h theme` 等价（自动去掉 `use` 前缀）。
+
+### 错误处理
+
+- 生成器目标已存在 → 报错并退出（退出码 1）
+- `hook` / `util` 的目标包不存在 → 报错并提示先执行 `cvw g pkg <name>`
+- `view` 找不到 `// cvw:routes` 锚点 → 跳过路由注册并提示手写
+
+## 生成物结构
+
+```
+my-app/
+├── apps/
+│   └── web/                    # @my-app/web，private，永不发包
+│       └── src/
+├── packages/
+│   ├── ui/                     # @my-app/ui，组件聚合包
+│   ├── utils/                  # @my-app/utils，纯 TS 工具
+│   └── button/                 # cvw g c 生成，独立组件包
+│       ├── index.ts
+│       ├── button.component.tsx
+│       ├── button.props.ts
+│       ├── composition/
+│       ├── __tests__/
+│       ├── package.json
+│       └── vite.config.ts
+├── pnpm-workspace.yaml
+├── tsconfig.base.json
+└── .changeset/
+```
+
+组件骨架遵循《Farris UI Vue 组件开发规范》：`index.ts` + `<name>.component.tsx` + `<name>.props.ts` + `composition/` + `__tests__/`，组件名 `F` 前缀、选择器 `f-` 前缀。
+
+## 开发约定
+
+- 内部包引用一律使用 `workspace:*`，不要写死版本号
+- 应用通过 Vite alias 直连 `packages/*/src` 源码，改库无需重新构建
+- 依赖方向单向：`utils -> 组件包 -> ui -> apps`，禁止反向依赖
+- `apps/*` 已在 `.changeset/config.json` 中 `ignore`，不会参与发布
+
+## 版本管理与发布
+
+```bash
+pnpm changeset           # 记录变更
+pnpm version-packages    # 升版本、生成 CHANGELOG
+pnpm release             # 构建并发布到 npm
+```
+
+## 本地开发（本仓库）
+
+```bash
+pnpm install
+pnpm dev       # 直接运行 CLI（tsx）
+pnpm play      # 生成一份真实产物到 playground/ 预览（覆盖全部生成器）
+pnpm test      # 单元测试
+pnpm typecheck # 类型检查
+pnpm build     # unbuild -> dist
+```
+
+## 发布本 CLI
+
+采用「构建 + 收集」两段式：`npm run build` 先产出 CLI，再把发包所需文件收集到 `dist/create-vue-workspace/`，形成一个**自包含的可发布包**。
+
+```
+dist/create-vue-workspace/
+├── package.json      # 已裁剪：无 scripts / devDependencies / private
+├── README.md
+├── LICENSE
+├── dist/index.mjs    # CLI 产物
+└── templates/        # 全部模板
+```
+
+发布：
+
+```bash
+npm login                          # 首次发布需先登录
+npm run build                      # unbuild + 收集到 dist/create-vue-workspace/
+cd dist/create-vue-workspace
+npm pack --dry-run                 # 自检：应只含 dist/ + templates/ + README + LICENSE + package.json
+npm publish
+```
+
+或一步到位（先构建再发布）：
+
+```bash
+npm run publish:dist
+```
+
+约定与注意事项：
+
+- 仓库根 `package.json` 标记了 `private: true`，表明它本身不是对外发布的包；请始终从 `dist/create-vue-workspace/` 发布
+- 升版本在仓库根执行 `npm version patch|minor|major`，再重新 `npm run build`
+- 暂存目录由每次 `npm run build` 重建（`unbuild` 会先清空 `dist/`），因此发布前务必先 build，避免发出陈旧产物
+- 若改为 scoped 包名，需保留 `publishConfig.access: "public"`
+
+> 本 CLI 仓库自身未接入 changesets（changesets 只出现在生成物模板中），版本号由 `npm version` 手动维护。