@farris/cli 2.3.2 → 2.3.4

package/templates/create/AGENTS.md

@@ -1,9 +1,17 @@
 # <%= title %> — AI 协作契约
 
-本文件是本 workspace 的**唯一真源**。子工程内不放任何 AI 配置文件；所有工具（Claude Code / Cursor / Windsurf / Copilot / Codex / Zed / VS Code …）都读这一份。
+本文件是本 workspace 的**唯一真源**：所有 AI 协作约定都写在这里。根目录 `CLAUDE.md` 只是指向本文件的一行指针。
+
+## 项目速览
+
+<%= projectOverview %>
 
 ## 1. 全局契约
 
+### AI 文件落点
+
+- 只在 workspace 根保留本文件（唯一真源）与 `CLAUDE.md`（一行指针）；**子工程内不得新增任何 AI 配置文件**（`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.windsurfrules` 等），公共约定一律写在本文件里。
+
 ### 目录分层
 
 | 目录 | 含义 | 构建产物 |
@@ -11,6 +19,8 @@
 | `<%= appContainer %>/` | 应用，可部署 | `dist/` |
 | `<%= libContainer %>/` | 组件库，可发布 | `lib/` |
 
+两类容器目录按需生成：只有存在对应类型的工程时才出现（首次 `add-app` / `add-lib` 时自动补建），不用空目录占位。
+
 ### 命令契约
 
 | 命令 | 作用 |
@@ -19,10 +29,12 @@
 | `farris-cli add-app <name>` | 添加应用 |
 | `farris-cli add-lib <name>` | 添加组件库 |
 | `farris-cli create-app [name]` | 在当前位置就地创建独立工程（不要用于 workspace 内） |
-| `farris-cli workspace create [target]` | workspace 初始化（等价于 create） |
+| `farris-cli workspace create [target]` | `create` 的适配器（参数与行为一致） |
 | `farris-cli workspace verify` | 校验 workspace 规范 |
 
-### 根脚本
+- 改动 workspace 结构、根脚本、容器、配置或增删工程后，执行 `pnpm verify` 自检，不通过先修复再提交。
+
+### 命令速查
 
 <%= commandTable %>
 
@@ -30,7 +42,19 @@
 
 - 依赖版本统一由根 `pnpm-workspace.yaml` 的 `catalog:` 提供；子工程里属于 catalog 的依赖一律写 `"catalog:"`。
 - 禁止手工 `npm install` 单个子包；禁止手改 `pnpm-workspace.yaml` 的 `packages` glob 或 `catalog` 版本。
-- 根脚本一律 `pnpm --recursive --if-present run <script>`。**根目录没有 `dev` / `preview` 是有意为之**：长驻服务不递归执行，避免多工程抢端口、日志交织。
+- 除 `verify` / `add-app` / `add-lib` 是 CLI 转发外，其余根脚本一律 `pnpm --recursive --if-present run <script>`。**根目录没有 `dev` / `preview` 是有意为之**：长驻服务不递归执行，避免多工程抢端口、日志交织。
+
+### 数据来源与 Mock
+
+- 开发期接口数据默认来自工程内 `mock/` 目录，写法与行为见该目录 README；未命中请求按 `farris.config.mjs` 的 `proxy` 转发，联调真实后端在**工程目录内**执行 `pnpm dev --no-mock`，业务代码不改动。
+- 请求路径必须与 mock 的 url 逐字一致；禁止在组件内散落假数据；mock 不得进入构建产物。
+
+### 工程内生成器
+
+- `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` 不会生效。
 
 ## 2. 工程类型差异速查表
 

package/templates/create/README.md

@@ -12,6 +12,8 @@
 └── package.json        # 根脚本
 ```
 
+两类容器目录按需生成：只有存在对应类型的工程时才出现（首次 `add-app` / `add-lib` 时自动补建），不会被空目录占位。
+
 ## 快速上手
 
 ```bash

package/templates/lib/components/index.ts

@@ -1,10 +1,3 @@
-import type { App } from 'vue';
-import { Button } from './button';
-
-export { Button };
-
-export default {
-  install(app: App) {
-    app.use(Button);
-  }
-};
+// 发布物唯一入口（当前为空组件仓库）。
+// 在 components/ 下新增组件后，在此做命名导出；需要全局安装时可用 ../components/common 的 withInstall 包装。
+export {};

package/templates/lib/src/App.vue

@@ -1,7 +1,5 @@
-<script setup lang="ts">
-import { Button } from '../components';
-</script>
+<script setup lang="ts"></script>
 
 <template>
-  <Button type="primary">Lib demo</Button>
+  <p>这是一个空组件仓库。在 components/ 下添加组件后，可在此预览。</p>
 </template>

package/templates/lib/test/index.spec.ts

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

package/templates/lib/test/index.spec.tsx

@@ -0,0 +1,9 @@
+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');
+
+    expect(entry).toBeDefined();
+  });
+});

package/templates/mobile/farris.config.mjs

@@ -1,7 +1,7 @@
 import { fileURLToPath, URL } from 'node:url';
 
 export default {
-  // 相对路径 base：微前端（IBP）与静态托管（iGIX iframe）都适用
+  // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
   base: './',
   routerMode: 'hash',
   // iife: IBP 微前端单文件产物（默认）；如需普通 ESM 站点产物，执行 pnpm build:es
@@ -23,6 +23,12 @@ export default {
   ],
   // 插件 默认值 [vue(), vueJsx()] 不要重复添加
   // plugins: [],
+  // 开发期 mock 默认开启：接口数据来自工程内 mock/ 目录，未命中的请求按下方 proxy 转发
+  // mock: true,
+  // 开发代理：未命中 mock 的接口转发到真实后端；联调时执行 pnpm dev --no-mock 可整体关闭 mock
+  // proxy: {
+  //   '/api': { target: 'http://localhost:8080', changeOrigin: true }
+  // },
   // viteConfig 配置项
   viteConfig: {}
 };

package/templates/mobile/mock/README.md

@@ -0,0 +1,34 @@
+# mock 目录
+
+开发期接口数据。一个领域一个文件，命名 `*.mock.ts`，默认导出路由数组：
+
+```ts
+export default [
+  {
+    url: '/api/v1/users', // 必须与代码中的请求路径逐字一致
+    method: 'GET', // 默认 GET
+    timeout: 300, // 可选 模拟延迟毫秒
+    status: 200, // 可选 响应状态码
+    response: ({ query, params, body }) => ({
+      data: [],
+      total: 0
+    })
+  }
+];
+```
+
+规则：
+
+- url 必须与代码中的请求路径逐字一致，见 `src/api/` 下的接口模块。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`；查询参数不写进 url，在 response 的 `query` 里读取。
+- mock 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。
+- 同一 url 不允许在多个 mock 文件中重复定义，重复时开发服务启动即报错。
+- mock 只用于开发期：不进构建产物，也不要在组件里散落假数据。
+
+行为：
+
+- 命中 mock → 返回 mock 数据。
+- 未命中 → 按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径 → 返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。

package/templates/mobile/src/App.tsx

@@ -0,0 +1,21 @@
+import { defineComponent } from 'vue';
+import { RouterLink, RouterView } from 'vue-router';
+
+export default defineComponent({
+  name: 'App',
+  setup() {
+    return () => (
+      <>
+        <header>
+          <div class="wrapper">
+            <nav>
+              <RouterLink to="/">Home</RouterLink>
+              <RouterLink to="/about">About</RouterLink>
+            </nav>
+          </div>
+        </header>
+        <RouterView />
+      </>
+    );
+  }
+});

package/templates/mobile/src/components/TheButton.tsx

@@ -0,0 +1,9 @@
+import { defineComponent } from 'vue';
+import { Button } from '@farris/mobile-ui-vue';
+
+export default defineComponent({
+  name: 'TheButton',
+  setup() {
+    return () => <Button>按钮</Button>;
+  }
+});

package/templates/mobile/src/main.ts

@@ -1,7 +1,7 @@
 import { createApp, type App as VueApp } from 'vue';
 import FarrisVue from '@farris/mobile-ui-vue';
 import '@farris/mobile-ui-vue/style.css';
-import App from './App.vue';
+import App from './App';
 import router from './router';<%= styleImport %>
 import { localResources } from './locales';
 

package/templates/mobile/src/router/index.ts

@@ -6,12 +6,12 @@ export const routes: RouteRecordRaw[] = [
   {
     path: '/',
     name: 'Home',
-    component: () => import('../views/HomeView.vue')
+    component: () => import('../views/HomeView')
   },
   {
     path: '/about',
     name: 'About',
-    component: () => import('../views/AboutView.vue')
+    component: () => import('../views/AboutView')
   }
 ];
 

package/templates/mobile/src/views/AboutView.tsx

@@ -0,0 +1,12 @@
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+  name: 'AboutView',
+  setup() {
+    return () => (
+      <div class="about">
+        <h1>This is an about page</h1>
+      </div>
+    );
+  }
+});

package/templates/mobile/src/views/HomeView.tsx

@@ -0,0 +1,13 @@
+import { defineComponent } from 'vue';
+import TheButton from '../components/TheButton';
+
+export default defineComponent({
+  name: 'HomeView',
+  setup() {
+    return () => (
+      <main>
+        <TheButton />
+      </main>
+    );
+  }
+});

package/templates/mobile/test/src/components/TheButton.spec.ts

@@ -1,12 +1,12 @@
 import { mount } from '@vue/test-utils';
 import { describe, expect, it } from 'vitest';
-import TheButton from '../../../src/components/TheButton.vue';
+import TheButton from '../../../src/components/TheButton';
 
 describe('TheButton', () => {
   it('mounts and renders its default slot', () => {
     const wrapper = mount(TheButton, {
       global: {
-        stubs: { 'fm-button': { template: '<button><slot /></button>' } }
+        stubs: { FmButton: { template: '<button><slot /></button>' } }
       }
     });
 

package/templates/mobile/test/src/components/TheButton.spec.tsx

@@ -1,12 +1,12 @@
 import { mount } from '@vue/test-utils';
 import { describe, expect, it } from 'vitest';
-import TheButton from '../../../src/components/TheButton.vue';
+import TheButton from '../../../src/components/TheButton';
 
 describe('TheButton (tsx collection)', () => {
   it('is collected by the unified vitest include', () => {
     const wrapper = mount(TheButton, {
       global: {
-        stubs: { 'fm-button': { template: '<button><slot /></button>' } }
+        stubs: { FmButton: { template: '<button><slot /></button>' } }
       }
     });
 

package/templates/web/farris.config.mjs

@@ -1,7 +1,7 @@
 import { fileURLToPath, URL } from 'node:url';
 
 export default {
-  // 相对路径 base：微前端（IBP）与静态托管（iGIX iframe）都适用
+  // 相对路径 base：微前端（IBP）与 iframe 嵌入场景都适用
   base: './',
   routerMode: 'hash',
   // iife: IBP 微前端单文件产物（默认）；如需普通 ESM 站点产物，执行 pnpm build:es
@@ -23,6 +23,12 @@ export default {
   ],
   // 插件 默认值 [vue(), vueJsx()] 不要重复添加
   // plugins: [],
+  // 开发期 mock 默认开启：接口数据来自工程内 mock/ 目录，未命中的请求按下方 proxy 转发
+  // mock: true,
+  // 开发代理：未命中 mock 的接口转发到真实后端；联调时执行 pnpm dev --no-mock 可整体关闭 mock
+  // proxy: {
+  //   '/api': { target: 'http://localhost:8080', changeOrigin: true }
+  // },
   // viteConfig 配置项
   viteConfig: {}
 };

package/templates/web/mock/README.md

@@ -0,0 +1,34 @@
+# mock 目录
+
+开发期接口数据。一个领域一个文件，命名 `*.mock.ts`，默认导出路由数组：
+
+```ts
+export default [
+  {
+    url: '/api/v1/users', // 必须与代码中的请求路径逐字一致
+    method: 'GET', // 默认 GET
+    timeout: 300, // 可选 模拟延迟毫秒
+    status: 200, // 可选 响应状态码
+    response: ({ query, params, body }) => ({
+      data: [],
+      total: 0
+    })
+  }
+];
+```
+
+规则：
+
+- url 必须与代码中的请求路径逐字一致，见 `src/api/` 下的接口模块。
+- 路径参数在 url 里用 `:参数名` 表示，例如 `/api/v1/users/:id`；查询参数不写进 url，在 response 的 `query` 里读取。
+- mock 响应体必须能被工程的 HTTP 客户端正确消费，形状跟着客户端出口走。
+- 同一 url 不允许在多个 mock 文件中重复定义，重复时开发服务启动即报错。
+- mock 只用于开发期：不进构建产物，也不要在组件里散落假数据。
+
+行为：
+
+- 命中 mock → 返回 mock 数据。
+- 未命中 → 按 `farris.config.mjs` 的 `proxy` 配置转发真实后端。
+- 未命中且未配代理的 `/api` 路径 → 返回 404 并提示，便于排查漏配。
+
+开关：在工程目录执行 `pnpm dev` 默认生效；`pnpm dev --no-mock` 或 `MOCK=none pnpm dev` 进入真实后端联调。

package/templates/web/src/App.tsx

@@ -0,0 +1,25 @@
+import { defineComponent } from 'vue';
+import { RouterLink, RouterView } from 'vue-router';
+import { setupMicroAppContext } from './micro/context';
+
+export default defineComponent({
+  name: 'App',
+  setup() {
+    // 微前端环境：订阅主应用下发的上下文（语言 / 主题）
+    setupMicroAppContext();
+
+    return () => (
+      <>
+        <header>
+          <div class="wrapper">
+            <nav>
+              <RouterLink to="/">Home</RouterLink>
+              <RouterLink to="/about">About</RouterLink>
+            </nav>
+          </div>
+        </header>
+        <RouterView />
+      </>
+    );
+  }
+});

package/templates/web/src/components/TheButton.tsx

@@ -0,0 +1,9 @@
+import { defineComponent } from 'vue';
+import { FButton } from '@farris/ui-vue';
+
+export default defineComponent({
+  name: 'TheButton',
+  setup() {
+    return () => <FButton>按钮</FButton>;
+  }
+});

package/templates/web/src/main.ts

@@ -1,7 +1,7 @@
 import { createApp, type App as VueApp } from 'vue';
 import FarrisVue from '@farris/ui-vue';
 import '@farris/ui-vue/index.css';
-import App from './App.vue';
+import App from './App';
 import router from './router';<%= styleImport %>
 import { localResources } from './locales';
 

package/templates/web/src/router/index.ts

@@ -6,12 +6,12 @@ export const routes: RouteRecordRaw[] = [
   {
     path: '/',
     name: 'Home',
-    component: () => import('../views/HomeView.vue')
+    component: () => import('../views/HomeView')
   },
   {
     path: '/about',
     name: 'About',
-    component: () => import('../views/AboutView.vue')
+    component: () => import('../views/AboutView')
   }
 ];
 

package/templates/web/src/views/AboutView.tsx

@@ -0,0 +1,12 @@
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+  name: 'AboutView',
+  setup() {
+    return () => (
+      <div class="about">
+        <h1>This is an about page</h1>
+      </div>
+    );
+  }
+});

package/templates/web/src/views/HomeView.tsx

@@ -0,0 +1,13 @@
+import { defineComponent } from 'vue';
+import TheButton from '../components/TheButton';
+
+export default defineComponent({
+  name: 'HomeView',
+  setup() {
+    return () => (
+      <main>
+        <TheButton />
+      </main>
+    );
+  }
+});

package/templates/web/test/src/components/TheButton.spec.ts

@@ -1,12 +1,12 @@
 import { mount } from '@vue/test-utils';
 import { describe, expect, it } from 'vitest';
-import TheButton from '../../../src/components/TheButton.vue';
+import TheButton from '../../../src/components/TheButton';
 
 describe('TheButton', () => {
   it('mounts and renders its default slot', () => {
     const wrapper = mount(TheButton, {
       global: {
-        stubs: { 'f-button': { template: '<button><slot /></button>' } }
+        stubs: { FButton: { template: '<button><slot /></button>' } }
       }
     });
 

package/templates/web/test/src/components/TheButton.spec.tsx

@@ -1,12 +1,12 @@
 import { mount } from '@vue/test-utils';
 import { describe, expect, it } from 'vitest';
-import TheButton from '../../../src/components/TheButton.vue';
+import TheButton from '../../../src/components/TheButton';
 
 describe('TheButton (tsx collection)', () => {
   it('is collected by the unified vitest include', () => {
     const wrapper = mount(TheButton, {
       global: {
-        stubs: { 'f-button': { template: '<button><slot /></button>' } }
+        stubs: { FButton: { template: '<button><slot /></button>' } }
       }
     });
 

package/templates/lib/components/button/index.ts

@@ -1,7 +0,0 @@
-import Button from './src/button.vue';
-import { withInstall } from '../common/with-install';
-
-const FButton = withInstall(Button);
-
-export { FButton as Button };
-export default FButton;

package/templates/lib/components/button/src/button.scss

@@ -1,10 +0,0 @@
-.f-button {
-  display: inline-flex;
-  align-items: center;
-  padding: 4px 12px;
-}
-
-.f-button--primary {
-  color: #fff;
-  background: #2e77e5;
-}

package/templates/lib/components/button/src/button.vue

@@ -1,12 +0,0 @@
-<script setup lang="ts">
-defineOptions({ name: 'Button' });
-defineProps<{
-  type?: 'primary' | 'default';
-}>();
-</script>
-
-<template>
-  <button class="f-button" :class="{ 'f-button--primary': type === 'primary' }">
-    <slot />
-  </button>
-</template>

package/templates/lib/test/components/button/button.spec.ts

@@ -1,11 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { Button } from '../../../../components/button/index';
-
-describe('Button', () => {
-  it('renders its default slot', () => {
-    const wrapper = mount(Button, { slots: { default: 'OK' } });
-
-    expect(wrapper.text()).toContain('OK');
-  });
-});

package/templates/lib/test/components/button/button.spec.tsx

@@ -1,11 +0,0 @@
-import { mount } from '@vue/test-utils';
-import { describe, expect, it } from 'vitest';
-import { Button } from '../../../../components/button/index';
-
-describe('Button (tsx collection)', () => {
-  it('is collected by the unified vitest include', () => {
-    const wrapper = mount(Button, { slots: { default: 'OK' } });
-
-    expect(wrapper.text()).toContain('OK');
-  });
-});

package/templates/mobile/src/App.vue

@@ -1,80 +0,0 @@
-<script setup lang="ts">
-import { RouterLink, RouterView } from 'vue-router';
-</script>
-
-<template>
-  <header>
-    <div class="wrapper">
-      <nav>
-        <RouterLink to="/">Home</RouterLink>
-        <RouterLink to="/about">About</RouterLink>
-      </nav>
-    </div>
-  </header>
-
-  <RouterView />
-</template>
-
-<style scoped>
-header {
-  line-height: 1.5;
-  max-height: 100vh;
-}
-
-.logo {
-  display: block;
-  margin: 0 auto 2rem;
-}
-
-nav {
-  width: 100%;
-  font-size: 12px;
-  text-align: center;
-  margin-top: 2rem;
-}
-
-nav a.router-link-exact-active {
-  color: var(--color-text);
-}
-
-nav a.router-link-exact-active:hover {
-  background-color: transparent;
-}
-
-nav a {
-  display: inline-block;
-  padding: 0 1rem;
-  border-left: 1px solid var(--color-border);
-}
-
-nav a:first-of-type {
-  border: 0;
-}
-
-@media (min-width: 1024px) {
-  header {
-    display: flex;
-    place-items: center;
-    padding-right: calc(var(--section-gap) / 2);
-  }
-
-  .logo {
-    margin: 0 2rem 0 0;
-  }
-
-  header .wrapper {
-    display: flex;
-    place-items: flex-start;
-    flex-wrap: wrap;
-  }
-
-  nav {
-    text-align: left;
-    margin-left: -1rem;
-    font-size: 1rem;
-
-    padding: 1rem 0;
-    margin-top: 1rem;
-  }
-}
-</style>

package/templates/mobile/src/components/TheButton.vue

@@ -1,3 +0,0 @@
-<template>
-  <fm-button>按钮</fm-button>
-</template>

package/templates/mobile/src/views/AboutView.vue

@@ -1,15 +0,0 @@
-<template>
-  <div class="about">
-    <h1>This is an about page</h1>
-  </div>
-</template>
-
-<style>
-@media (min-width: 1024px) {
-  .about {
-    min-height: 100vh;
-    display: flex;
-    align-items: center;
-  }
-}
-</style>

package/templates/mobile/src/views/HomeView.vue

@@ -1,9 +0,0 @@
-<script setup lang="ts">
-import TheButton from '../components/TheButton.vue';
-</script>
-
-<template>
-  <main>
-    <TheButton />
-  </main>
-</template>