@bams-app/work-cli 0.0.1

package/README.md

@@ -0,0 +1,235 @@
+# @bams-app/work-cli
+
+BAMS-Work 全局开发工具（类似 vue-cli 模式），提供**项目初始化**与**组件开发命令**。
+
+## 设计思路
+
+`work-cli` 是**薄壳**，不内嵌任何模板/服务/能力包代码，全部复用 work 仓库发布到 npm 的包：
+
+| 能力 | 来源包 |
+| --- | --- |
+| 项目/组件创建 | `@bams-app/create-ui-component`、`@bams-app/create-ui-page`、`@bams-app/create-ui-base`（内部引用 `@bams-app/ui-*-template`） |
+| 开发服务 / 构建 | `@bams-app/ui-dev-server`（serve / build-app / build-umd） |
+| 环境变量加载 | `@bams-app/shared-env` |
+| 环境配置创建 | `@bams-app/create-env`（交互式生成 `.envs/.env.dev-<alias>`） |
+| 动态入口生成 | `@bams-app/create-pages-entry`（扫描 page-*/ui-* 生成 build-components-entry.js） |
+| 批量页面创建 | `@bams-app/create-pages-from-components`（批量将 ui-* 转为 page-*，复用 create-ui-page） |
+| 公共配置 | `@bams-app/configs`（app-config.json、可配置组件插槽默认值，被 ui-dev-server 与 store 依赖） |
+
+- `create` 生成 **scope 目录模式** Monorepo：根 `workspaces: ["bams-components/*", "*-ui/*", "bams-ui"]`，
+  业务组件按 scope 目录存放（`energy-ui/ui-xxx`）。
+- 项目根 `package.json` 只声明 `@bams-app/ui-dev-server` 与能力包，**不声明任何外部运行时依赖**；
+  项目模板 `.npmrc` 配置 `install-links=true`，`npm install` 时以复制方式安装 `file:` 链接的包
+  并解析其全部传递依赖（vue、ant-design-vue 等随能力包自动安装）。
+- 能力包（`work/packages`、`work/ui`、`work/configs` 下的全部运行时包，含 ui 组件）声明
+  **以 ui-dev-server 的 dependencies 为单一来源**：本地验证模式逐个 `file:` 注入 work 本地
+  目录，发布后模式由 ui-dev-server 的 dependencies 随 npm 自动安装，业务组件与 runtime
+  共用同一份根 node_modules。
+- 所有命令通过 `require.resolve()` 定位 work 包 bin 并以子进程委托执行，`WORK_PROJECT_ROOT` 环境变量注入项目根。
+
+### 整体架构
+
+```mermaid
+flowchart LR
+    subgraph WORK["work 仓库（52 个可发布包）"]
+        A["能力包<br/>packages/ · ui/ · configs/"]
+        B["开发工具<br/>cli/（ui-dev-server · create-* · template）"]
+    end
+    subgraph REG["私有 registry<br/>npm.hedpy.cn"]
+        C["@bams-app/*"]
+    end
+    subgraph CLI["@bams-app/work-cli（薄壳）"]
+        D["create / add / dev / build / umd<br/>env / pages-entry / pages-from-components"]
+    end
+    subgraph PROJ["用户项目（Monorepo）"]
+        E["package.json<br/>仅声明 @bams-app/*"]
+        F["npm install<br/>install-links=true · 复制安装并解析传递依赖"]
+    end
+    A -->|"publish-all / 单包 npm publish"| C
+    B -->|"发布 + 依赖声明"| C
+    C -->|"registry 安装"| CLI
+    C -->|"发布后随 npm 自动安装"| PROJ
+    CLI -->|"create 以 file: 注入"| PROJ
+    CLI -->|"子进程委托 work 包 bin"| B
+    E --> F
+```
+
+```
+用户项目（Monorepo，scope 目录模式）
+├── package.json            # workspaces: bams-components/*、*-ui/*、bams-ui
+├── .bams-work/             # BAMS-Work 项目标记目录（勿删除）
+├── .envs/.env.dev-<env>    # 环境变量
+├── .proxy.js               # 自定义代理（可选）
+├── bams-components/
+│   └── ui-component-demo   # 示例组件
+└── energy-ui/              # 业务 scope 目录
+    └── ui-order-list
+```
+
+## 安装
+
+```bash
+npm i -g @bams-app/work-cli
+```
+
+## 使用
+
+```bash
+# 初始化 Monorepo 项目模版
+bams-work create my-bams-project
+cd my-bams-project
+npm install
+
+# 启动 work 开发环境（加载 .envs/.env.dev-<env>）
+bams-work dev demo                 # 默认组件 ui-component-demo
+bams-work dev demo ui-order-list   # 指定组件
+
+# 构建宿主应用（production，输出 dist/）
+bams-work build ui-order-list
+
+# 构建组件 UMD 产物（输出 dist/umd/）
+bams-work umd ui-order-list
+
+# 在 scope 目录下创建新组件
+bams-work add --dir energy-ui --name ui-order-list
+bams-work add --dir energy-ui --name page-order-list --type page
+bams-work add --dir bams-components --name ui-base-btn --type base
+
+# 升级 @bams-app 包（查询最新版并重装依赖）
+bams-work update
+```
+
+### 命令一览
+
+| 命令 | 说明 |
+| --- | --- |
+| `create <name>` | 初始化 Monorepo 项目模版（含示例组件与 `.bams-work/` 标记） |
+| `add --dir <scope> --name <name>` | 在 scope 目录下创建组件（component/page/base），并注册 workspace |
+| `dev <env> [component]` | 启动 work 开发环境（复用 ui-dev-server serve） |
+| `build [component]` | 构建宿主应用（复用 build-app，production） |
+| `umd [component]` | 构建组件 UMD 产物（复用 build-umd） |
+| `env [--force]` | 交互式创建开发环境配置 `.envs/.env.dev-<alias>`（复用 create-env） |
+| `update [--skip-install]` | 升级 `@bams-app` 包：查询最新版本、更新 ui-dev-server 声明并重装依赖 |
+| `pages-entry --dir <dir> --type <page\|component>` | 扫描 page-*/ui-* 目录生成 webpack 动态入口（复用 create-pages-entry） |
+| `pages-from-components --dir <dir>` | 批量将 ui-* 组件转为 page-* 页面（复用 create-pages-from-components） |
+
+### 组件目录规范
+
+业务组件（`<scope>/ui-xxx`）包含：`index.js`、`package.json`（`@<scope>/ui-xxx`）、
+`src/`（`apis` / `business` / `constants` / `i18n` / `mock` / `theme` / `component.vue`）。
+
+## 开发环境机制
+
+- `.envs/.env.dev-<env>`：环境配置，`dev <env>` 时由 `@bams-app/shared-env` 加载。
+- 代理：项目根 `.proxy.js`（参考 `.proxy.js.example`）。
+- webpack 扩展：项目根 `vue.config.extend.js`（导出对象或 `({ env, projectRoot }) => 对象`）。
+- 可配置插槽：`COMPONENT_*` 环境变量 + `@configurable/*` 别名（login / header / startr-layout）。
+- 能力包可选组件（未安装时）由 `OPTIONAL_PACKAGE_FALLBACKS` 兜底 alias 到空入口，保证编译不报错。
+
+## 发布流程
+
+所有 work 包统一发布到 npm registry，**默认官方 npm（registry.npmjs.org）**，通过环境变量
+`NPM_REGISTRY` 可随时切换到私有 registry（如 `https://npm.hedpy.cn/`）。work 下所有含
+`package.json` 的目录（`packages/`、`cli/`、`ui/`、`configs/` 等）都会被打包发布，
+`private` 包自动跳过：
+
+```bash
+# 0. 登录对应 registry（每次切换目标后需重新登录）
+npm login --registry=https://registry.npmjs.org/        # 发布官方
+npm login --registry=https://npm.hedpy.cn/             # 切到私服时
+
+# 1. 在仓库根目录一键发布全部 work 包（交互式选择版本，只升不降）
+yarn publish-all                                        # 默认发布官方 npm
+NPM_REGISTRY=https://npm.hedpy.cn/ yarn publish-all    # 发布到私服
+
+# 2. 发布 work-cli 本体（dependencies 改为 registry 版本号后）
+cd work-cli && npm publish
+```
+
+### 单包发布
+
+仅修改了某个包时，可跳过批量发布，直接在该包目录 `npm publish --registry=<目标>`（`private`
+包无法发布，版本号已存在时需先手动修改该包 `package.json` 的 version）：
+
+```bash
+cd work/packages/utils && npm publish --registry=https://registry.npmjs.org/
+cd work/ui/ui-header-component && npm publish --registry=https://registry.npmjs.org/
+cd work/cli/create-ui-component && npm publish --registry=https://registry.npmjs.org/
+cd work/configs && npm publish --registry=https://registry.npmjs.org/
+```
+
+单包发布只影响该包，其他包版本号不变；需要整体提升版本时使用 `yarn publish-all`。
+发布官方 npm 时 `@bams-app` scope 会随首个 scoped 包自动创建，无需预先注册。
+
+能力包（`@bams-app/*`，含 `work/ui` 下的 ui 组件包）由 `ui-dev-server` 的 dependencies
+统一声明，发布后随 `npm install` 自动安装到用户项目，无需逐包注入。
+
+发布后 work-cli 的 `dependencies` 应从 `file:../work/cli/...` 改为对应 registry 版本号
+（`^0.1.0` 等），`create` 生成的项目则声明 `"@bams-app/ui-dev-server": "^0.1.0"`。
+
+## 用户项目升级
+
+用户项目依赖 `@bams-app/*` 的方式决定升级方式：本地验证模式为 `file:` 引用 work 本地包，
+发布后模式仅直接依赖 `@bams-app/ui-dev-server`（`^0.1.0`），能力包由 ui-dev-server 的
+dependencies（`"*"`）传递安装。
+
+### 一键升级（推荐）
+
+```bash
+bams-work update
+```
+
+自动完成：本地 file: 模式清除 node_modules 中的 file: 依赖缓存后重装，强制同步 work 最新
+源码；发布后模式查询 registry 最新版本 → 更新 `package.json` 中 ui-dev-server 声明 →
+重新 `npm install`（能力包 `*` 范围自动对齐最新）。`--skip-install` 可跳过重装。
+
+### 本地验证模式（file:）
+
+能力包以复制方式安装（`.npmrc` 的 `install-links=true`）。npm 对已安装的 file: 依赖会直接
+跳过（即使源码已变化），`bams-work update` 会先清除 node_modules 中全部 file: 依赖缓存
+再重装，强制重新复制 work 本地最新源码：
+
+```bash
+bams-work update
+```
+
+### 发布后模式（registry）
+
+| 场景 | 命令 |
+| --- | --- |
+| 常规升级（同大版本线 0.1.x） | `npm update @bams-app/ui-dev-server` |
+| 跨大版本（0.1 → 0.2） | 改 package.json 为 `"@bams-app/ui-dev-server": "^0.2.0"` 后 `npm install` |
+| 全部能力包强制最新 | `npm update`，或删除 node_modules 与 package-lock.json 后重装 |
+
+`npm update <pkg>` 会把 ui-dev-server 升到其版本范围允许的最新版，并同步更新依赖树中的
+能力包（`"*"` 范围 → 最新）；跨大版本超出 `^` 约束，需手动修改版本号。
+
+### 前提
+
+- 升级前确保对应版本已发布：`"*"` 只解析 registry 上已发布的版本。
+- registry 指向：项目 `.npmrc` 的 `@bams-app:registry` 决定从哪个源拉取 `@bams-app/*`；
+  发布到官方 npm 后需移除/注释该行（或改为官方源），否则升级拉取的仍是私服版本。
+
+## 本地验证（未发布时）
+
+未发布时通过 `file:` 引用本地 work 包完成端到端验证（`create` 会自动探测 work 仓库根，
+将 ui-dev-server 与能力包以 `file:` 注入项目依赖，无需手动设置环境变量）。
+注意：项目 `.npmrc` 的 `install-links=true` 使 `file:` 包以复制方式安装，
+修改 work 包源码后需重新执行 `npm install` 才会生效：
+
+```bash
+cd work-cli && npm install      # 安装 file: 依赖（链接 work/cli 下的包）
+npm link                        # 全局链接 bams-work
+
+cd /tmp && rm -rf demo-app
+bams-work create demo-app        # 自动以 file: 引用本地 ui-dev-server 与能力包
+cd demo-app && npm install
+bams-work dev demo               # 应返回 HTTP 200
+bams-work build ui-component-demo
+bams-work umd ui-component-demo
+bams-work add --dir energy-ui --name ui-order-list
+```
+
+## 环境要求
+
+- Node.js >= 16.7.0

package/bin/work-cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { colorize } = require('../lib/utils');
+
+const pkg = require('../package.json');
+
+const COMMANDS = {
+    create: '初始化 Monorepo 项目模版',
+    add: '在 scope 目录下创建组件（component/page/base）',
+    dev: '启动 work 开发环境（serve，复用 ui-dev-server）',
+    build: '构建宿主应用（production，复用 ui-dev-server）',
+    umd: '构建组件 UMD 产物（复用 build-umd）',
+    env: '创建开发环境配置（.envs/.env.dev-<alias>）',
+    update: '升级 @bams-app 包（更新 ui-dev-server 并重装依赖）',
+    'pages-entry': '扫描 page-*/ui-* 目录生成 webpack 动态入口',
+    'pages-from-components': '批量将 ui-* 组件转为 page-* 页面'
+};
+
+function printUsage() {
+    console.log('');
+    console.log(colorize('BAMS-Work CLI', 'cyan'), colorize(`v${pkg.version}`, 'gray'));
+    console.log(colorize('复用 work 已发布的包（ui-dev-server / shared-env / create-ui-*）', 'gray'));
+    console.log('');
+    console.log(colorize('用法:', 'bold'));
+    console.log('  bams-work <command> [options]');
+    console.log('');
+    console.log(colorize('命令:', 'bold'));
+    Object.entries(COMMANDS).forEach(([name, desc]) => {
+        console.log(`  ${colorize(name.padEnd(20), 'green')} ${desc}`);
+    });
+    console.log('');
+    console.log(colorize('示例:', 'bold'));
+    console.log('  bams-work create my-bams-project        # 初始化 Monorepo 项目');
+    console.log('  bams-work add --dir energy-ui --name ui-order-list');
+    console.log('  bams-work dev demo ui-component-demo    # 启动 work 开发环境');
+    console.log('  bams-work build ui-component-demo       # 构建宿主应用');
+    console.log('  bams-work umd ui-component-demo --out dist   # 构建 UMD 产物');
+    console.log('  bams-work env demo                          # 创建开发环境配置');
+    console.log('  bams-work update                            # 升级 @bams-app 包');
+    console.log('  bams-work pages-entry --dir energy-ui --type page');
+    console.log('  bams-work pages-from-components --dir energy-ui');
+    console.log('');
+}
+
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        printUsage();
+        process.exit(command ? 0 : 1);
+    }
+
+    if (command === '--version' || command === '-v' || command === 'version') {
+        console.log(pkg.version);
+        process.exit(0);
+    }
+
+    const commandPath = path.resolve(__dirname, '../commands', `${command}.js`);
+    if (!fs.existsSync(commandPath)) {
+        console.error(colorize(`未知命令: ${command}`, 'red'));
+        printUsage();
+        process.exit(1);
+    }
+
+    const handler = require(commandPath);
+    await handler(args);
+}
+
+main().catch((err) => {
+    console.error(colorize('[work-cli] 错误:', 'red'), err.message || err);
+    process.exit(1);
+});

package/commands/add.js

@@ -0,0 +1,143 @@
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { findProjectRoot, toKebabCase, error, success, info } = require('../lib/utils');
+
+/**
+ * 用法: bams-work add --dir <scope> --name <name> [--type component|page|base]
+ *       [--template <tpl>] [--use-component <name>] [--desc <text>]
+ */
+function parseArgs(args) {
+    const params = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+            params[key] = next;
+            i++;
+        } else {
+            params[key] = true;
+        }
+    }
+    return params;
+}
+
+/**
+ * 将 scope 目录注册到项目根 workspaces（如 energy-ui → "energy-ui/*"）
+ */
+function ensureWorkspaceScope(projectRoot, scopeDir) {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        return;
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const pattern = `${scopeDir}/*`;
+    const workspaces = Array.isArray(pkg.workspaces) ? pkg.workspaces : [];
+    if (!workspaces.includes(pattern)) {
+        workspaces.push(pattern);
+        pkg.workspaces = workspaces;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+        info(`已注册 workspace: ${pattern}`);
+    }
+}
+
+function resolveCreateBin(type) {
+    const pkgName = {
+        component: '@bams-app/create-ui-component',
+        page: '@bams-app/create-ui-page',
+        base: '@bams-app/create-ui-base'
+    }[type];
+    if (!pkgName) {
+        error(`不支持的组件类型: ${type}（可选 component / page / base）`);
+        process.exit(1);
+    }
+    return require.resolve(`${pkgName}/bin/${pkgName.split('/').pop()}.js`);
+}
+
+async function runCreateBin(createBin, binArgs) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [createBin, ...binArgs], {
+            stdio: 'inherit'
+        });
+        child.on('error', (err) => {
+            error(`创建失败: ${err.message}`);
+            resolve(1);
+        });
+        child.on('exit', (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}
+
+async function main(args) {
+    const params = parseArgs(args);
+
+    if (!params.name) {
+        error('用法: bams-work add --dir <scope> --name <name> [--type component|page|base]');
+        error('示例: bams-work add --dir energy-ui --name ui-order-list');
+        error('      bams-work add --dir energy-ui --name page-order-list --type page');
+        process.exit(1);
+    }
+
+    if (!params.dir) {
+        error('请提供 --dir <scope>（组件所在 scope 目录名，如 energy-ui）');
+        process.exit(1);
+    }
+
+    const projectRoot = findProjectRoot(process.cwd());
+    if (!projectRoot) {
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        process.exit(1);
+    }
+
+    const type = params.type || 'component';
+    const scopeDir = path.basename(path.resolve(params.dir));
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(scopeDir)) {
+        error(`scope 目录名不合法: ${scopeDir}（必须使用小写字母、数字和中横线，如 energy-ui）`);
+        process.exit(1);
+    }
+
+    // 将 scope 目录注册到项目 workspaces
+    ensureWorkspaceScope(projectRoot, scopeDir);
+
+    // 委托对应 create-ui-* 包（复用 work 的模板与命令）
+    const createBin = resolveCreateBin(type);
+
+    const binArgs = [
+        '--dir', path.resolve(projectRoot, scopeDir),
+        '--name', toKebabCase(params.name)
+    ];
+    if (params.template) {
+        binArgs.push('--template', params.template);
+    }
+    if (params['use-component']) {
+        binArgs.push('--use-component', params['use-component']);
+    }
+    if (params.desc) {
+        binArgs.push('--desc', params.desc);
+    }
+    binArgs.push('--no-install');
+
+    const code = await runCreateBin(createBin, binArgs);
+    if (code !== 0) {
+        error('组件创建失败');
+        process.exit(code);
+    }
+
+    success(`组件创建成功: ${toKebabCase(params.name)}（scope: ${scopeDir}）`);
+    info(`开发: bams-work dev <env> ${toKebabCase(params.name)}`);
+    info(`UMD: bams-work umd ${toKebabCase(params.name)}`);
+}
+
+module.exports = main;
+
+if (require.main === module) {
+    main(process.argv.slice(2)).catch((err) => {
+        error(err.message || err);
+        process.exit(1);
+    });
+}

package/commands/build.js

@@ -0,0 +1,83 @@
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot, error, info, run } = require('../lib/utils');
+
+/**
+ * 用法: bams-work build [component] [-- <vue-cli args>]
+ * 委托 @bams-app/ui-dev-server/bin/build-app.js 构建宿主应用（production）
+ */
+async function main(args) {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (!projectRoot) {
+        error('未找到 BAMS-Work 项目（缺少 .bams-work 目录），请先执行 bams-work create <name>');
+        process.exit(1);
+    }
+
+    let component = '';
+    let serviceArgs = [];
+    let i = 0;
+
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === '--') {
+            serviceArgs = args.slice(i + 1);
+            break;
+        } else if (arg === '--component' || arg === '-c') {
+            component = args[i + 1];
+            i += 2;
+        } else if (arg.startsWith('--')) {
+            serviceArgs = args.slice(i);
+            break;
+        } else if (!component) {
+            component = arg;
+        } else {
+            serviceArgs = args.slice(i);
+            break;
+        }
+        i++;
+    }
+
+    let buildAppBin;
+    let sharedEnvBin;
+    try {
+        buildAppBin = require.resolve('@bams-app/ui-dev-server/bin/build-app.js');
+        sharedEnvBin = require.resolve('@bams-app/shared-env/bin/shared-env.js');
+    } catch (err) {
+        error('未安装 work 依赖包，请先在 work-cli 目录执行 npm install');
+        process.exit(1);
+    }
+
+    info(`构建宿主应用，组件: ${component || 'ui-component-demo'}`);
+    info(`工作目录: ${projectRoot}`);
+
+    const uiArgs = [buildAppBin];
+    if (component) {
+        uiArgs.push('-c', component);
+    }
+    uiArgs.push(...serviceArgs);
+
+    const env = { ...process.env, WORK_PROJECT_ROOT: projectRoot };
+
+    // 存在 .env.production 时通过 shared-env 加载，否则直接构建
+    const prodEnvFile = '.envs/.env.production';
+    let code;
+    if (fs.existsSync(path.join(projectRoot, prodEnvFile))) {
+        code = await run(
+            process.execPath,
+            [sharedEnvBin, '--project', '.', '--env', prodEnvFile, '--', ...uiArgs],
+            { cwd: projectRoot, env }
+        );
+    } else {
+        code = await run(process.execPath, uiArgs, { cwd: projectRoot, env });
+    }
+    process.exit(code);
+}
+
+module.exports = main;
+
+if (require.main === module) {
+    main(process.argv.slice(2)).catch((err) => {
+        error(err.message || err);
+        process.exit(1);
+    });
+}