@farris/cli 2.3.7 → 2.3.9

package/lib/plugins/msw-adapter.js

@@ -0,0 +1,141 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+/** @farris/cli 目前适配的 msw 主版本（应用的 msw 由模板声明、随工作区 catalog 统一） */
+const SUPPORTED_MAJOR = 2;
+const toPosix = (p) => p.split('\\').join('/');
+/** 路径比较统一按 posix + 小写（Windows 下 server 侧给的是 C:/...，本地 join 给的是 C:\...） */
+const normalize = (p) => toPosix(p).toLowerCase();
+// handleRequest 的 emitter 参数只用于生命周期事件通知，dev 期无需监听；
+// msw 未从包根导出该类型，按参数位置断言，避免额外依赖 strict-event-emitter
+const noopEmitter = { emit() { } };
+const sharedOptions = { onUnhandledRequest: () => null };
+const loadingRuntimes = new Map();
+async function resolveAppMsw(appRoot) {
+    const require = createRequire(join(appRoot, 'package.json'));
+    let entry;
+    let pkgPath;
+    try {
+        // 先按包名解析：pnpm 下命中应用自己的 node_modules，npm 下命中提升后的 node_modules
+        pkgPath = require.resolve('msw/package.json');
+        entry = require.resolve('msw');
+    }
+    catch (err) {
+        throw new Error(`未能在应用目录解析到 msw（${appRoot}）：请先在应用工程内安装依赖（msw 已由应用模板放入 devDependencies）。` +
+            `若工程由旧版脚手架创建，请升级 @farris/cli 或手动执行 pnpm add -D msw@^2。原因：` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+    const version = String(JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '');
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    if (major !== SUPPORTED_MAJOR) {
+        throw new Error(`应用安装的 msw 版本为 ${version}，@farris/cli 目前只适配 ${SUPPORTED_MAJOR}.x：` +
+            `请把应用里的 msw 对齐到 ${SUPPORTED_MAJOR}.x（工作区 catalog 已统一版本）`);
+    }
+    const mod = (await import(pathToFileURL(entry).href));
+    const handleRequest = mod.handleRequest ?? mod.default?.handleRequest;
+    if (typeof handleRequest !== 'function') {
+        throw new Error(`msw ${version} 的入口未导出 handleRequest（${entry}），无法执行 mock handler`);
+    }
+    return { handleRequest, version };
+}
+/**
+ * 从应用目录解析并加载 msw（应用 devDependencies 里的那一份）。
+ * 同一应用目录只加载一次；加载失败不缓存，装好依赖后重试即可。
+ */
+export function loadAppMsw(appRoot) {
+    const cached = loadingRuntimes.get(appRoot);
+    if (cached) {
+        return cached;
+    }
+    const loading = resolveAppMsw(appRoot);
+    loadingRuntimes.set(appRoot, loading);
+    loading.catch(() => loadingRuntimes.delete(appRoot));
+    return loading;
+}
+/** 读取 handler 的 info（方法/路径），用于重复路径校验 */
+export function handlerInfo(handler) {
+    return handler.info ?? {};
+}
+/** 默认导出的项是否为 MSW 的 HTTP handler */
+export function isRequestHandler(value) {
+    return !!value && typeof handlerInfo(value).method === 'string';
+}
+/** 是否位于指定目录内（按 posix、大小写不敏感比较，并要求完整目录边界，避免同名前缀目录误判） */
+export function isInsideDir(file, dir) {
+    const target = normalize(file);
+    const base = normalize(dir).replace(/\/+$/, '');
+    return target === base || target.startsWith(`${base}/`);
+}
+/** 非流式场景下的请求体读取（按 chunk 收集） */
+function readBufferedBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(String(chunk)));
+        req.on('end', () => resolve(chunks.length > 0 ? chunks.join('') : undefined));
+        req.on('error', () => resolve(undefined));
+    });
+}
+/** 把 Node 请求转成 fetch Request（handleRequest 的输入） */
+export async function toWebRequest(req, origin) {
+    const method = (req.method ?? 'GET').toUpperCase();
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    const init = {
+        method,
+        headers: new Headers(req.headers)
+    };
+    if (hasBody) {
+        // 真实 dev server 下 req 是可读流，直接流式交给 fetch；测试替身等场景退化为缓冲读取
+        init.duplex = 'half';
+        init.body =
+            req.readable && typeof Readable.toWeb === 'function'
+                ? Readable.toWeb(req)
+                : await readBufferedBody(req);
+    }
+    return new Request(new URL(req.url ?? '/', origin), init);
+}
+/** 把 fetch Response 流式写回 Node 响应 */
+async function writeResponse(res, response) {
+    res.statusCode = response.status;
+    if (response.statusText) {
+        res.statusMessage = response.statusText;
+    }
+    response.headers.forEach((value, name) => {
+        // appendHeader 才符合多值头（如 set-cookie）的语义，Node 18.3 起可用
+        if (typeof res.appendHeader === 'function') {
+            res.appendHeader(name, value);
+        }
+        else {
+            res.setHeader(name, value);
+        }
+    });
+    if (response.body) {
+        try {
+            await pipeline(Readable.fromWeb(response.body), res);
+        }
+        catch {
+            // 客户端提前断开或响应流异常：连接已不可用，回收即可，不向上抛
+            res.destroy();
+        }
+        return;
+    }
+    res.end();
+}
+/**
+ * 用应用侧的 msw 处理一次请求。
+ * 命中 mock 时写回响应并返回状态码；未命中返回 null，由调用方放行给代理或 404 守卫。
+ */
+export async function runMockHandlers(req, res, handlers, runtime) {
+    const origin = `http://${req.headers.host ?? 'localhost'}`;
+    const request = await toWebRequest(req, origin);
+    const response = await runtime.handleRequest(request, randomUUID(), handlers, sharedOptions, noopEmitter, { resolutionContext: { baseUrl: origin } });
+    if (!response) {
+        return null;
+    }
+    await writeResponse(res, response);
+    return response.status;
+}
+//# sourceMappingURL=msw-adapter.js.map

package/lib/plugins/msw-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msw-adapter.js","sourceRoot":"","sources":["../../src/plugins/msw-adapter.ts"],"names":[],"mappings":"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"}

package/lib/plugins/replace.js

@@ -1,18 +1,18 @@
-import { getPackageName } from '../common/constant.js';
-export function replace(path) {
-    return {
-        name: 'farris-replace-path',
-        renderChunk(code, chunk) {
-            const fileNames = chunk.fileName.split('.');
-            const format = fileNames[fileNames.length - 2];
-            // const regExpress = new RegExp(/@farris\/mobile-ui-vue\/([\w-]+)/g);
-            const dynamicRegExp = new RegExp(`${getPackageName().replace(/\//g, '\\/')}\\/([\\w-]+)`, // 自动转义斜杠
-            'g');
-            return code.replace(dynamicRegExp, (match, captureGroup) => {
-                return path(format, [captureGroup]);
-            });
-        }
-    };
-}
-;
+import { getPackageName } from '../common/constant.js';
+export function replace(path) {
+    return {
+        name: 'farris-replace-path',
+        renderChunk(code, chunk) {
+            const fileNames = chunk.fileName.split('.');
+            const format = fileNames[fileNames.length - 2];
+            // const regExpress = new RegExp(/@farris\/mobile-ui-vue\/([\w-]+)/g);
+            const dynamicRegExp = new RegExp(`${getPackageName().replace(/\//g, '\\/')}\\/([\\w-]+)`, // 自动转义斜杠
+            'g');
+            return code.replace(dynamicRegExp, (match, captureGroup) => {
+                return path(format, [captureGroup]);
+            });
+        }
+    };
+}
+;
 //# sourceMappingURL=replace.js.map

package/lib/plugins/systemjs-bundle.js

@@ -1,16 +1,16 @@
-export function systemjsBundle() {
-    return {
-        name: 'systemjs-bundle',
-        outputOptions(options) {
-            if (options.format === 'systemjs') {
-                return {
-                    ...options,
-                    name: undefined
-                };
-            }
-            return options;
-        }
-    };
-}
-;
+export function systemjsBundle() {
+    return {
+        name: 'systemjs-bundle',
+        outputOptions(options) {
+            if (options.format === 'systemjs') {
+                return {
+                    ...options,
+                    name: undefined
+                };
+            }
+            return options;
+        }
+    };
+}
+;
 //# sourceMappingURL=systemjs-bundle.js.map

package/lib/plugins/systemjs-bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"systemjs-bundle.js","sourceRoot":"","sources":["../../src/plugins/systemjs-bundle.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,aAAa,CAAC,OAAY;YACxB,IAAG,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE;gBAChC,OAAO;oBACL,GAAG,OAAO;oBACV,IAAI,EAAE,SAAS;iBAChB,CAAC;aACH;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAAA,CAAC"}
+{"version":3,"file":"systemjs-bundle.js","sourceRoot":"","sources":["../../src/plugins/systemjs-bundle.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,aAAa,CAAC,OAAY;YACxB,IAAG,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBACjC,OAAO;oBACL,GAAG,OAAO;oBACV,IAAI,EAAE,SAAS;iBAChB,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AAAA,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@farris/cli",
     "private": false,
-    "version": "2.3.7",
+    "version": "2.3.9",
     "type": "module",
     "typings": "lib/index.d.ts",
     "exports": {
@@ -38,6 +38,7 @@
         "@vitejs/plugin-vue-jsx": "^3.0.0",
         "esbuild": "^0.23.0",
         "esbuild-sass-plugin": "^3.3.1",
+        "msw": "^2.15.0",
         "typescript": "^5.7.3",
         "vite": "^5.4.19",
         "vite-plugin-css-injected-by-js": "^3.5.2",
@@ -56,6 +57,9 @@
         "esbuild-sass-plugin": {
             "optional": true
         },
+        "msw": {
+            "optional": true
+        },
         "typescript": {
             "optional": true
         },
@@ -75,6 +79,7 @@
         "@vitejs/plugin-vue-jsx": "^3.0.0",
         "esbuild": "^0.23.0",
         "esbuild-sass-plugin": "^3.3.1",
+        "msw": "^2.15.0",
         "rimraf": "^5.0.7",
         "sass": "^1.90.0",
         "typescript": "^5.7.3",

package/templates/create/.gitignore.tpl

@@ -1,13 +1,33 @@
-node_modules
-dist
-dist-es
-package
-lib
+# 依赖与产物
+node_modules/
+dist/
+dist-es/
+dist-ssr/
+coverage/
+*.tsbuildinfo
+.pnpm-store/
+
+# 日志与本地文件
+*.log
 .DS_Store
 *.local
+.env
+.env.*
+!.env.example
+package-lock.json
+
+# 编辑器
 .vscode/*
 !.vscode/extensions.json
 !.vscode/settings.json
-.idea
-*.log
-.pnpm-store
+.idea/
+.history
+*.sw?
+
+# AI 工具
+.codebuddy/
+.cursor/
+.claude/
+.windsurf/
+.trae/
+.opencode/

package/templates/create/AGENTS.md

@@ -1,6 +1,7 @@
 # <%= title %> — AI 协作契约
 
-本文件是本 workspace 的**唯一真源**：所有 AI 协作约定都写在这里。根目录 `CLAUDE.md` 只是指向本文件的一行指针。
+本文件是本 workspace 的 **唯一真源**：所有 AI 协作约定都写在这里。
+根目录 `CLAUDE.md` 只是指向本文件的一行指针；**子工程内不得新增任何 AI 配置文件**（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.windsurfrules` 等），公共约定一律写在本文件里。
 
 ## 项目速览
 
@@ -12,76 +13,106 @@
 
 ## 2. 全局契约
 
-### AI 文件落点
+### 2.1 必须遵守
 
-- 只在 workspace 根保留本文件（唯一真源）与 `CLAUDE.md`（一行指针）；**子工程内不得新增任何 AI 配置文件**（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.windsurfrules` 等），公共约定一律写在本文件里。
+| 规则 | 具体做法 |
+|---|---|
+| 改完代码先跑测试 | 在**工程目录内** `pnpm test`；提交前在根目录跑一次 `pnpm test`（递归全部工程） |
+| 改结构 / 根脚本 / 容器 / 增删工程 | 先 `pnpm verify`，不通过先修复再提交 |
+| 依赖版本只有一个来源 | 子工程里属于 catalog 的依赖一律写 `"catalog:"`；禁止手工 `npm install` 单个子包；禁止手改 `catalog` 版本与 `packages` glob |
+| 不许为了"变绿"动测试设施 | 禁止改 `vitest.config.ts` 的 `include` / `exclude` / `environment`，禁止删改既有用例 |
+| AI 配置只放 workspace 根 | 见文首：子工程内不放任何 AI 配置文件 |
+| 长驻命令在工程目录内执行 | 根目录**没有** `dev` / `preview`（有意为之）：`cd <工程目录>` 后再 `pnpm dev` |
 
-### 目录分层
+### 2.2 目录与落点
 
-| 目录 | 含义 | 构建产物 |
+| 目录 | 放什么 | 怎么出现 |
 |---|---|---|
-| `<%= appContainer %>/` | 应用，可部署 | `dist/` |
-| `<%= libContainer %>/` | 组件库，可发布 | `lib/` |
-
-两类容器目录按需生成：只有存在对应类型的工程时才出现（首次 `add-app` / `add-lib` 时自动补建），不用空目录占位。
+| `<%= appContainer %>/` | 应用、微应用（可部署） | `add-app` / `add-micro` 按需创建 |
+| `<%= libContainer %>/` | 组件库（可发布） | `add-lib` 按需创建 |
 
-### 命令契约
+- 微应用与普通应用**同在 `<%= appContainer %>/` 容器**，靠工程 `package.json` 的 `"farris": { "type": "micro" }` 区分；**不存在** `micro/` 容器。
+- 容器按需出现，不用空目录占位；工程目录名即包名来源。
 
-| 命令 | 作用 |
-|---|---|
-| `npm create farris [name]` / `farris-cli create [name]` | 新建 workspace（可同时创建一个工程） |
-| `farris-cli add-app <name>` | 添加应用 |
-| `farris-cli add-lib <name>` | 添加组件库 |
-| `farris-cli create-app [name]` | 在当前位置就地创建独立工程（不要用于 workspace 内） |
-| `farris-cli workspace create [target]` | `create` 的适配器（参数与行为一致） |
-| `farris-cli workspace verify` | 校验 workspace 规范 |
+### 2.3 命令
 
-- 改动 workspace 结构、根脚本、容器、配置或增删工程后，执行 `pnpm verify` 自检，不通过先修复再提交。
+<%= commandTable %>
 
-### 命令速查
+### 2.4 产物与交付
 
-<%= commandTable %>
+| 工程类型 | 默认构建 | 产物目录 |
+|---|---|---|
+| 应用 | `pnpm build` → `es` + `umd` + `systemjs` | `dist/`、`dist-umd/`、`dist-systemjs/` |
+| 微应用 | `pnpm build` → `iife` 单文件 | `dist/` |
+| 组件库 | `pnpm build` → 一次构建出全部格式 | `dist/` |
 
-### 依赖契约
+- **产物目录一律是 `dist/` 系列**（组件库的发布清单 `files` 也是 `dist`）；不要再写 `lib/` 之类旧目录。
+- 只出某一种格式：工程目录内 `pnpm build:es`（应用另有 `pnpm build:umd` / `pnpm build:systemjs`）。
+- 微应用交付 `iife` 单文件是 IBP 契约；普通应用**不默认**产出 `iife`，需要时显式执行 `farris-cli build --format iife`。
 
-- 依赖版本统一由根 `pnpm-workspace.yaml` 的 `catalog:` 提供；子工程里属于 catalog 的依赖一律写 `"catalog:"`。
-- 禁止手工 `npm install` 单个子包；禁止手改 `pnpm-workspace.yaml` 的 `packages` glob 或 `catalog` 版本。
-- 除 `verify` / `add-app` / `add-lib` 是 CLI 转发外，其余根脚本一律 `pnpm --recursive --if-present run <script>`。**根目录没有 `dev` / `preview` 是有意为之**：长驻服务不递归执行，避免多工程抢端口、日志交织。
+### 2.5 数据来源与 Mock
 
-### 数据来源与 Mock
+- 开发期接口数据默认来自工程内 `mock/` 目录，用 **MSW handler** 写法（见该目录 README）；未命中请求按 `farris.config.mjs` 的 `proxy` 转发。
+- 联调真实后端：在**工程目录内**执行 `pnpm dev --no-mock`（或 `MOCK=none pnpm dev`），业务代码不改。
+- 请求路径必须与 mock 的 `url` 逐字一致；禁止在组件里散落假数据。
+- mock 不得进入构建产物：`msw` 已在应用 `devDependencies`（开发期依赖），不要在 `mock/` 之外引用它，也不要把它加到 `dependencies`。
 
-- 开发期接口数据默认来自工程内 `mock/` 目录，写法与行为见该目录 README；未命中请求按 `farris.config.mjs` 的 `proxy` 转发，联调真实后端在**工程目录内**执行 `pnpm dev --no-mock`，业务代码不改动。
-- 请求路径必须与 mock 的 url 逐字一致；禁止在组件内散落假数据；mock 不得进入构建产物。
+### 2.6 工程内生成器
 
-### 工程内生成器
+| 命令 | 作用 | 关键参数 |
+|---|---|---|
+| `farris-cli generate view <name>` | 生成页面 | `--with-route` 自动注册路由；`--with-props` 生成 Props |
+| `farris-cli generate component <name>` | 生成组件到 `<工程>/src/components/<name>/` | `--with-props`；`--style none\|css\|scss`（默认 `none`） |
+| `farris-cli generate api <name> -e /api/v1/orders` | 生成 `src/api/` 接口模块 | `-m get` 指定方法 |
 
-- `farris-cli generate view <name> [--with-route] [--with-props]`：生成页面；`--with-route` 自动注册路由。
-- `farris-cli generate component <name> [--style none|css|scss]`：生成 `src/components/` 通用组件。
-- `farris-cli generate api <name> -e /api/v1/orders [-m get]`：生成 `src/api/` 接口模块。
-- 路由注册依赖 `src/router/index.ts`（或 `src/router/routes.ts`）中的 `routes = [...]` 赋值形式数组；自己重写 router 必须保留该形式，否则 `--with-route` 不会生效。
+- `--with-route` 依赖 `src/router/index.ts`（或 `src/router/routes.ts`）里的 `routes = [...]` 赋值形式；自己重写 router 必须保留该写法，否则不生效。
 
 ## 3. 工程类型差异速查表
 
-| 关注点 | 应用 `<%= appContainer %>/<name>` | 组件库 `<%= libContainer %>/<name>` |
-|---|---|---|
-| 源码位置 | `src/` | `components/` 是**发布物唯一入口**；`src/` 仅供本地演示 |
-| 构建 | `farris-cli build` | `farris-cli build-lib -ep && farris-cli build-components` |
-| 产物 | `dist/` | `lib/` |
-| 发版 | 不单独发版（`private: true`） | `pnpm changeset` |
-| 测试 | `test/` 镜像 `src/` 路径 | `test/` 镜像 `components/` 与 `src/` 路径 |
+| 关注点 | 应用 `<%= appContainer %>/<name>` | 微应用 `<%= appContainer %>/<name>`（`farris.type: micro`） | 组件库 `<%= libContainer %>/<name>` |
+|---|---|---|---|
+| 源码位置 | `src/` | `src/` | `components/` 是**发布物唯一入口**；`src/` 仅供本地演示 |
+| 构建 | `pnpm build` | `pnpm build`（`iife` 单文件） | `pnpm build`（`farris-cli build-lib -ep` + `farris-cli build-components`） |
+| 产物 | `dist/`、`dist-umd/`、`dist-systemjs/` | `dist/` | `dist/` |
+| 宿主契约 | **不暴露** | 暴露 `window.mount` / `window.unmount`，并处理宿主下发的 `initialPath` 深链 | —— |
+| 发版 | 不单独发版（`private: true`） | 不单独发版（`private: true`） | `pnpm changeset` |
+| 测试 | 就近 `__tests__/` | 就近 `__tests__/` | 就近 `__tests__/`（贴 `components/` 或 `src/` 下被测文件） |
 
-**高频陷阱：** 组件写在组件库的 `src/` 下等于「写了但发不出去」——`farris-cli build-components` 只扫 `components/`。
+**两个高频陷阱：**
+
+1. 组件写进组件库的 `src/` 等于「写了但发不出去」——`farris-cli build-components` 只扫 `components/`。
+2. 普通应用**没有**宿主契约：不要往应用里加 `window.mount` / `__MICRO_APP_ENVIRONMENT__`，也不会生成 `src/micro/`、`src/micro-app.d.ts`；需要微前端能力就用 `farris-cli add-micro <name>` 新建微应用。
 
 ## 4. 测试约定
 
-测试路径 = 被测文件相对工程根的路径，前缀 `test/`，扩展名换成 `.spec.ts` / `.spec.tsx`：
+### 4.1 放哪儿（就近：与被测文件同级）
 
 ```text
-<%= libContainer %>/button/components/button/src/button.vue
-  → <%= libContainer %>/button/test/components/button/src/button.spec.ts
+<%= appContainer %>/shop/src/components/button/button.component.tsx
+  → <%= appContainer %>/shop/src/components/button/__tests__/button.spec.tsx
+
+<%= libContainer %>/ui-kit/components/button/button.component.tsx
+  → <%= libContainer %>/ui-kit/components/button/__tests__/button.spec.tsx
 ```
 
-工程内 `pnpm test` 跑本工程测试；根目录 `pnpm test` 递归跑全部工程。
+- 文件名 = 被测文件名 + `.spec`：纯逻辑用 `*.spec.ts`，组件或含 JSX 用 `*.spec.tsx`。
+- `__tests__/` 与被测文件同级；**不要**在工程根另建 `test/` 汇总目录。
+- 工程里**不预置**端到端测试：需要时自行引入，别与上面的单元测试混放。
+
+### 4.2 每次改动必须做
+
+1. 改完代码先在**工程目录内**跑 `pnpm test`；提交前在根目录跑一次 `pnpm test`（递归全部工程）。
+2. 新增或修改组件、工具函数、mock 解析逻辑：**同一提交内**补上或更新对应 `.spec`。
+3. 修 bug：先在 `.spec` 里写一条能复现的失败用例，再改实现（先红后绿）。
+4. 用例必须能在 `jsdom` 下独立通过：不依赖真实浏览器、不访问外网、不依赖执行顺序。
+
+### 4.3 禁止
+
+- 禁止为让测试通过而改 `vitest.config.ts` 的 `include` / `exclude` / `environment`，或删改既有用例。
+- 禁止把端到端用例放进 `__tests__/`；禁止提交 `.only` / `.skip`。
+- 禁止在用例里靠固定 `sleep` 等待，或依赖上一条用例残留的状态。
+
+工程内 `pnpm test` 只跑本工程；根目录 `pnpm test` 递归跑全部工程。
 
 ## 5. 子工程清单
 

package/templates/create/README.md

@@ -2,23 +2,56 @@
 
 <%= readmeBody %>
 
+本 workspace 用 pnpm 管理：根目录只放 workspace 级命令，工程内的开发 / 构建命令进工程目录执行。
+
+## 快速上手
+
+```bash
+pnpm install          # 安装依赖（版本由 pnpm-workspace.yaml 的 catalog 统一提供）
+pnpm build            # 构建全部工程（默认产出全部格式）
+pnpm test             # 跑全部工程的单元测试
+pnpm verify           # 校验 workspace 规范（改结构 / 脚本 / 容器后必跑）
+```
+
+开发某个工程时，进入它的目录：
+
+```bash
+cd <%= appContainer %>/shop    # 以应用为例：工程内的命令都在这里执行
+pnpm dev          # 启动开发服务器（根目录没有 dev，是有意为之）
+```
+
 ## 目录结构
 
 ```text
-├── <%= appContainer %>/       # 应用（可部署）
-├── <%= libContainer %>/       # 组件库（可发布）
-├── AGENTS.md          # AI 协作契约（唯一真源）
-├── pnpm-workspace.yaml # workspace 配置与 catalog 依赖版本
-└── package.json        # 根脚本
+<%= appContainer %>/            # 应用与微应用（可部署）
+<%= libContainer %>/            # 组件库（可发布）
+AGENTS.md            # AI 协作约定（唯一真源）
+CLAUDE.md            # 指向 AGENTS.md 的一行指针
+pnpm-workspace.yaml  # workspace 配置与 catalog 依赖版本
+package.json         # 根脚本
 ```
 
-两类容器目录按需生成：只有存在对应类型的工程时才出现（首次 `add-app` / `add-lib` 时自动补建），不会被空目录占位。
+容器目录按需出现：只有真正存在对应类型的工程时才生成，不用空目录占位。
+微应用与普通应用同住 `<%= appContainer %>/`，靠工程 `package.json` 的 `"farris": { "type": "micro" }` 区分。
 
-## 快速上手
+## 交付物在哪
+
+每个工程的产物都在自己的 `dist/` 系列目录里，组件库的发布清单（`files`）同样只指向 `dist`：
+
+| 工程类型 | 产物目录 |
+|---|---|
+| 应用 | `dist/`、`dist-umd/`、`dist-systemjs/` |
+| 微应用 | `dist/`（`iife` 单文件） |
+| 组件库 | `dist/`（一次构建出全部格式） |
+
+## 增删工程
 
 ```bash
-pnpm install
-pnpm --filter <pkg> dev   # 启动某个工程的开发服务器（根目录不提供 dev）
-pnpm build
-pnpm verify
+pnpm add-app shop        # 新增应用          → <%= appContainer %>/shop
+pnpm add-lib ui-kit      # 新增组件库        → <%= libContainer %>/ui-kit
+pnpm add-micro portal    # 新增微应用        → <%= appContainer %>/portal
 ```
+
+生成页面 / 组件 / 接口模块，在**工程目录内**执行 `farris-cli generate view|component|api <name>`。
+
+完整的命令表、测试约定、Mock 规则与工程类型差异，见 `AGENTS.md`。

package/templates/create/package.json

@@ -17,6 +17,7 @@
     "format": "pnpm --recursive --if-present run format",
     "verify": "farris-cli workspace verify",
     "add-app": "farris-cli add-app",
-    "add-lib": "farris-cli add-lib"
+    "add-lib": "farris-cli add-lib",
+    "add-micro": "farris-cli add-micro"
   }
 }

package/templates/lib/.gitignore.tpl

@@ -1,3 +1,33 @@
+# 依赖与产物
 node_modules/
-lib/
+dist/
+dist-es/
+dist-ssr/
+coverage/
+*.tsbuildinfo
+.pnpm-store/
+
+# 日志与本地文件
+*.log
+.DS_Store
+*.local
+.env
+.env.*
+!.env.example
 package-lock.json
+
+# 编辑器
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+.idea/
+.history
+*.sw?
+
+# AI 工具
+.codebuddy/
+.cursor/
+.claude/
+.windsurf/
+.trae/
+.opencode/

package/templates/lib/.gitlab-ci.yml

@@ -33,7 +33,7 @@ build-job:
     expire_in: '5days'
     name: 'dist'
     paths:
-      - $CI_PROJECT_DIR/lib
+      - $CI_PROJECT_DIR/dist
 
 publish-one:
   stage: publish
@@ -59,4 +59,4 @@ publish-one:
     - npm config fix
   script:
     - npm config set //repos.iec.io/repository/npm-igix-release/:_auth=$(echo -n ${ARTIFACTS_REPO_USERNAME}:${ARTIFACTS_REPO_PASSWORD} | base64)
-    - cd lib && npm publish
+    - cd dist && npm publish

package/templates/lib/README.md

@@ -1,3 +1,26 @@
 # <%= name %>
 
-`src/` 是本地演示应用，执行 `npm run dev` 启动。演示入口会自动加载 `components/**/*.scss`，新增组件样式无需再改 `src/main.ts`。发布到 npm 的组件源码在 `components/`，执行 `npm run build` 打包。
+Farris 组件库：`components/` 是**发布物唯一入口**，`src/` 只用于本地演示。
+
+## 常用命令
+
+```bash
+pnpm dev        # 启动本地演示（自动加载 components/**/*.scss，无需改 src/main.ts）
+pnpm test       # 跑单元测试（用例就近放在被测文件同级的 __tests__/）
+pnpm build      # 构建交付物 → dist/
+pnpm changeset  # 记一条变更；发版执行 pnpm version
+```
+
+## 目录职责
+
+| 目录 | 作用 |
+|---|---|
+| `components/` | 发布到 npm 的组件源码（唯一入口）——只有写在这里才会被打包 |
+| `components/**/__tests__/` | 组件测试，与被测文件同级 |
+| `src/` | 本地演示应用（`pnpm dev` 的入口），不参与发布 |
+| `dist/` | 构建产物；`package.json` 的 `files` 只发布它 |
+
+## 高频陷阱
+
+- 组件写在 `src/` 下等于「写了但发不出去」：`farris-cli build-components` 只扫 `components/`。
+- 改完组件记得在 `__tests__/` 补用例，并在提交前跑 `pnpm test`。

package/templates/lib/{test → components/__tests__}/index.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 
 describe('component library entry', () => {
   it('provides an empty publish entry', async () => {
-    const entry = await import('../components/index');
+    const entry = await import('../index');
 
     expect(entry).toBeDefined();
   });

package/templates/lib/{test → components/__tests__}/index.spec.tsx

@@ -1,8 +1,8 @@
 import { describe, expect, it } from 'vitest';
 
 describe('component library entry (tsx collection)', () => {
-  it('is collected by the unified vitest include', async () => {
-    const entry = await import('../components/index');
+  it('is collected by the default vitest include', async () => {
+    const entry = await import('../index');
 
     expect(entry).toBeDefined();
   });