@lark-apaas/fullstack-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -1,10 +1,12 @@
 # @lark-apaas/fullstack-cli
 
-> Fullstack 模板文件自动派生工具
+> Fullstack 开发工具集 - 文件派生、数据库 Schema 生成、OpenAPI 生成
 
 ## 功能
 
-自动派生和管理 fullstack 模板项目的文件和目录。
+1. **自动派生** - 自动管理项目脚本和配置文件
+2. **数据库 Schema 生成** - 从现有数据库生成 Drizzle ORM schema
+3. **OpenAPI 生成** - 自动生成 API 文档和客户端 SDK
 
 ## 安装
 
@@ -14,75 +16,168 @@ npm install --save-dev @lark-apaas/fullstack-cli
 
 ## 使用
 
-### 自动派生
+### 1. 自动派生
 
-每次运行 `npm install` 时，会根据配置自动派生文件到项目：
+每次运行 `npm install` 时，会自动派生文件到项目：
 
 **派生内容：**
-- `scripts/` - 脚本目录（总是覆盖）
+- `scripts/` - Shell 脚本目录（总是覆盖）
 - `.gitignore` - 追加 fullstack-cli 相关忽略规则
 
-### 重要提示
+⚠️ **`scripts/` 目录由 CLI 自动管理，请勿手动修改！**
 
-⚠️ **`scripts/` 目录由 `@lark-apaas/fullstack-cli` 自动管理，请勿手动修改！**
+### 2. 生成数据库 Schema
 
-每次安装依赖时，所有脚本文件会被自动覆盖为最新版本。
+从现有数据库生成 Drizzle ORM schema：
 
-## 配置
+```bash
+npm run gen:db-schema
+```
+
+**环境变量配置：**
+```bash
+# 必需
+SUDA_DATABASE_URL=postgresql://user:pass@host:port/dbname?schema=public
+
+# 可选
+DB_SCHEMA_OUTPUT=server/database/schema.ts  # 输出路径
+DRIZZLE_SCHEMA_FILTER=public,custom         # Schema 过滤器
+DRIZZLE_TABLES_FILTER=users,orders          # 表过滤器
+```
+
+**工作流程：**
+1. 从 `SUDA_DATABASE_URL` 读取数据库连接
+2. 使用 CLI 内置的 `drizzle.config.ts`（用户无需维护）
+3. 执行 `drizzle-kit introspect`
+4. 后处理 schema（通过 devtool-kits）
+5. 输出到 `server/database/schema.ts`
+
+### 3. 生成 OpenAPI 文档
+
+自动生成 OpenAPI 文档和客户端 SDK：
+
+```bash
+npm run gen:openapi
+```
+
+**环境变量配置：**
+```bash
+# 可选
+APP_MODULE_PATH=server/app.module    # AppModule 路径（不含扩展名）
+CLIENT_BASE_PATH=/                   # 客户端基础路径
+```
+
+**工作流程：**
+1. 动态导入用户项目的 `AppModule`
+2. 挂载 DevToolsModule
+3. 生成 OpenAPI 文档和客户端 SDK
+
+### 4. CLI 命令
+
+```bash
+# 查看帮助
+fullstack-cli --help
+
+# 生成数据库 schema
+fullstack-cli gen-db-schema
+
+# 生成 OpenAPI
+fullstack-cli gen-openapi
+
+# 查看版本
+fullstack-cli --version
+```
+
+## package.json 配置
+
+在用户项目的 `package.json` 中添加：
+
+```json
+{
+  "scripts": {
+    "gen:db-schema": "fullstack-cli gen-db-schema",
+    "gen:openapi": "NODE_ENV=development DEPRECATED_SKIP_INIT_DB_CONNECTION=true fullstack-cli gen-openapi"
+  },
+  "devDependencies": {
+    "@lark-apaas/fullstack-cli": "^0.1.0",
+    "drizzle-kit": "^0.20.0"  // 如果使用数据库功能
+  }
+}
+```
+
+## 技术细节
+
+### 派生配置
 
-派生规则通过 `src/postinstall.config.ts` 配置：
+派生规则在 `src/postinstall.config.ts` 中定义：
 
 ```typescript
 export default {
-  // 派生规则
   sync: [
-    // 派生整个目录
     {
       from: 'templates/scripts',
       to: 'scripts',
       type: 'directory',
       overwrite: true,
     },
-
-    // 追加内容到文件
     {
       from: 'templates/.gitignore.append',
       to: '.gitignore',
       type: 'append',
     },
   ],
-
-  // 文件权限设置
   permissions: {
     '**/*.sh': 0o755,
   },
 };
 ```
 
-### 支持的 sync type
+### Drizzle 配置
 
-- **directory** - 派生整个目录
-  - `overwrite: true` - 总是覆盖
-  - `overwrite: false` - 只复制不存在的文件
+CLI 内置 `templates/drizzle.config.ts`，通过环境变量动态配置：
+- 用户**无需**维护 `drizzle.config.ts`
+- 所有配置通过环境变量传递
+- 使用绝对路径指向用户项目
 
-- **file** - 派生单个文件
-  - `overwrite: true` - 总是覆盖
-  - `overwrite: false` - 仅当文件不存在时复制
+### OpenAPI 生成
 
-- **append** - 追加内容到文件末尾
-  - 自动去重，不会重复追加
+- 动态导入用户的 `AppModule`
+- 使用 `@lark-apaas/fullstack-nestjs-core` 的 DevToolsModule
+- 自动生成客户端 SDK
 
-## 工作原理
+## 依赖关系
 
-1. 在 `postinstall` 钩子中自动运行
-2. 检测是否在用户项目中（通过 `INIT_CWD`）
-3. 读取 `dist/postinstall.config.js` 配置（由 `src/postinstall.config.ts` 编译而来）
-4. 根据配置规则派生文件/目录
-5. 设置文件权限
-
-## 自定义需求
+```
+fullstack-cli
+  ↓ 依赖
+@lark-apaas/devtool-kits (核心逻辑)
+
+用户项目 peerDependencies:
+  - @nestjs/core (用于 gen-openapi)
+  - @lark-apaas/fullstack-nestjs-core (用于 gen-openapi)
+  - drizzle-kit (用于 gen-db-schema，可选)
+```
 
-如需自定义脚本或配置，请联系框架团队。
+## 升级说明
+
+### 从旧版本迁移
+
+**可以删除的文件：**
+- ❌ `scripts/gen-db-schema.ts` - 已内置到 CLI
+- ❌ `scripts/gen-openapi.ts` - 已内置到 CLI
+- ❌ `drizzle.config.ts` - 已由 CLI 管理
+
+**更新 package.json：**
+```diff
+{
+  "scripts": {
+-   "gen:db-schema": "ts-node scripts/gen-db-schema.ts",
++   "gen:db-schema": "fullstack-cli gen-db-schema",
+-   "gen:openapi": "nest start --entryFile ../scripts/gen-openapi",
++   "gen:openapi": "fullstack-cli gen-openapi"
+  }
+}
+```
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const command = process.argv[2];
+const distPath = path.join(__dirname, '..', 'dist');
+
+async function main() {
+  try {
+    switch (command) {
+      case 'gen-db-schema': {
+        const { run } = await import(path.join(distPath, 'commands', 'gen-db-schema.js'));
+        await run();
+        break;
+      }
+      case 'sync':
+      case 'postinstall': {
+        // 调用原有的 sync-scripts.js
+        require('./sync-scripts.js');
+        break;
+      }
+      case '--version':
+      case '-v': {
+        const pkg = require('../package.json');
+        console.log(pkg.version);
+        break;
+      }
+      case '--help':
+      case '-h':
+      case undefined: {
+        showHelp();
+        break;
+      }
+      default: {
+        console.error(`Unknown command: ${command}`);
+        console.error('');
+        showHelp();
+        process.exit(1);
+      }
+    }
+  } catch (error) {
+    console.error(`Failed to execute command "${command}":`, error.message);
+    process.exit(1);
+  }
+}
+
+function showHelp() {
+  console.log(`
+Usage: fullstack-cli <command> [options]
+
+Commands:
+  gen-db-schema     Generate database schema from existing database
+  sync              Sync template files to user project (internal use)
+
+Options:
+  --version, -v     Show version number
+  --help, -h        Show help
+
+Environment Variables:
+  # gen-db-schema
+  SUDA_DATABASE_URL       Database connection URL (required)
+  DB_SCHEMA_OUTPUT        Output path for schema (default: server/database/schema.ts)
+  DRIZZLE_SCHEMA_FILTER   Schema filter, comma-separated (optional)
+  DRIZZLE_TABLES_FILTER   Tables filter (default: *)
+
+Examples:
+  $ fullstack-cli gen-db-schema
+  $ DB_SCHEMA_OUTPUT=custom/schema.ts fullstack-cli gen-db-schema
+
+Scripts (auto-generated):
+  scripts/gen-openapi.ts  - Generate OpenAPI documentation (use: npm run gen:openapi)
+  scripts/gen-db-schema.ts - Generate database schema (deprecated, use CLI command)
+`);
+}
+
+main();

package/bin/sync-scripts.js

@@ -9,9 +9,8 @@ async function main() {
   const userProjectRoot = process.env.INIT_CWD || process.cwd();
   const pluginRoot = path.resolve(__dirname, '..');
 
-  // 如果在插件自己的目录，跳过
-  const isInstallingPlugin = __dirname.includes('/node_modules/@lark-apaas/fullstack-cli/');
-  if (isInstallingPlugin || userProjectRoot === pluginRoot) {
+  // 只有在插件自己的开发目录中才跳过（避免在开发插件时触发 sync）
+  if (userProjectRoot === pluginRoot) {
     console.log('[fullstack-cli] Skip syncing (installing plugin itself)');
     process.exit(0);
   }

package/dist/commands/gen-db-schema.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 生成数据库 schema
+ *
+ * 环境变量配置：
+ * - SUDA_DATABASE_URL: 数据库连接 URL（必需）
+ * - DB_SCHEMA_OUTPUT: schema 输出路径，默认 'server/database/schema.ts'
+ * - DRIZZLE_SCHEMA_FILTER: schema 过滤器，逗号分隔
+ * - DRIZZLE_TABLES_FILTER: 表过滤器，逗号分隔，默认 '*'
+ */
+export declare function run(): Promise<void>;

package/dist/commands/gen-db-schema.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+/**
+ * 生成数据库 schema
+ *
+ * 环境变量配置：
+ * - SUDA_DATABASE_URL: 数据库连接 URL（必需）
+ * - DB_SCHEMA_OUTPUT: schema 输出路径，默认 'server/database/schema.ts'
+ * - DRIZZLE_SCHEMA_FILTER: schema 过滤器，逗号分隔
+ * - DRIZZLE_TABLES_FILTER: 表过滤器，逗号分隔，默认 '*'
+ */
+export async function run() {
+    const databaseUrl = process.env.SUDA_DATABASE_URL;
+    if (!databaseUrl) {
+        console.error('[gen-db-schema] Error: SUDA_DATABASE_URL environment variable is required');
+        process.exit(1);
+    }
+    const outputPath = process.env.DB_SCHEMA_OUTPUT || 'server/database/schema.ts';
+    const OUT_DIR = path.resolve(process.cwd(), 'server/database/.introspect');
+    const SCHEMA_FILE = path.resolve(process.cwd(), outputPath);
+    console.log('[gen-db-schema] Starting...');
+    console.log(`[gen-db-schema] Output: ${outputPath}`);
+    // 使用 CLI 内部的 drizzle 配置
+    const cliRoot = path.resolve(__dirname, '../..');
+    const configPath = path.join(cliRoot, 'templates', 'drizzle.config.ts');
+    if (!fs.existsSync(configPath)) {
+        console.error('[gen-db-schema] Error: drizzle config not found in CLI package');
+        process.exit(1);
+    }
+    // 通过环境变量传递绝对路径给配置文件
+    const env = {
+        ...process.env,
+        __DRIZZLE_OUT_DIR__: OUT_DIR,
+        __DRIZZLE_SCHEMA_PATH__: SCHEMA_FILE,
+    };
+    // 执行 drizzle-kit introspect
+    const args = process.argv.slice(3);
+    const spawnArgs = ['--yes', 'drizzle-kit', 'introspect', '--config', configPath, ...args];
+    const result = spawnSync('npx', spawnArgs, { stdio: 'inherit', env });
+    if (result.error) {
+        console.error('[gen-db-schema] Execution failed:', result.error);
+        process.exit(result.status ?? 1);
+    }
+    if ((result.status ?? 0) !== 0) {
+        process.exit(result.status ?? 1);
+    }
+    // 复制生成的 schema
+    const generatedSchema = path.join(OUT_DIR, 'schema.ts');
+    if (!fs.existsSync(generatedSchema)) {
+        console.error('[gen-db-schema] schema.ts not generated');
+        process.exit(1);
+    }
+    fs.mkdirSync(path.dirname(SCHEMA_FILE), { recursive: true });
+    fs.copyFileSync(generatedSchema, SCHEMA_FILE);
+    console.log(`[gen-db-schema] ✓ Copied to ${outputPath}`);
+    // 后处理（如果 devtool-kits 可用）
+    try {
+        const { postprocessDrizzleSchema } = await import('@lark-apaas/devtool-kits');
+        const stats = postprocessDrizzleSchema(SCHEMA_FILE);
+        if (stats?.unmatchedUnknown?.length) {
+            console.warn('[gen-db-schema] Unmatched custom types detected:', stats.unmatchedUnknown);
+        }
+        console.log('[gen-db-schema] ✓ Postprocessed schema');
+    }
+    catch (error) {
+        console.warn('[gen-db-schema] Postprocess skipped (devtool-kits not available)');
+    }
+    // 清理临时文件
+    if (fs.existsSync(OUT_DIR)) {
+        fs.rmSync(OUT_DIR, { recursive: true, force: true });
+    }
+    console.log('[gen-db-schema] ✓ Complete');
+}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "CLI tool for fullstack template management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "fullstack-cli": "./bin/cli.js"
+  },
   "files": [
     "dist",
     "templates",
@@ -12,7 +15,7 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "postinstall": "node bin/sync-scripts.js && echo 'Fullstack CLI installation completed'"
+    "postinstall": "node bin/sync-scripts.js"
   },
   "keywords": [
     "fullstack",
@@ -27,6 +30,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lark-apaas/devtool-kits": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/core": "^10.0.0",
+    "@lark-apaas/fullstack-nestjs-core": "^1.0.0",
+    "drizzle-kit": "^0.20.0"
+  },
+  "peerDependenciesMeta": {
+    "drizzle-kit": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.9.2"

package/templates/.gitignore.append

@@ -1 +1,8 @@
-# ===
+
+# ==========================================
+# fullstack-cli managed files
+# ==========================================
+# scripts/ directory is auto-generated
+# DO NOT modify manually
+scripts/
+

package/templates/drizzle.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'drizzle-kit';
+
+// 这个配置会被 fullstack-cli 在运行时动态处理
+// 通过环境变量传递具体参数
+const outputDir = process.env.__DRIZZLE_OUT_DIR__ || './server/database/.introspect';
+const schemaPath = process.env.__DRIZZLE_SCHEMA_PATH__ || './server/database/schema.ts';
+const schemaFilter = process.env.DRIZZLE_SCHEMA_FILTER?.split(',') || [];
+const tablesFilter = process.env.DRIZZLE_TABLES_FILTER?.split(',') || ['*'];
+
+const parsedUrl = new URL(process.env.SUDA_DATABASE_URL || '');
+
+export default defineConfig({
+  schema: schemaPath,
+  out: outputDir,
+  tablesFilter,
+  schemaFilter,
+  dialect: 'postgresql',
+  dbCredentials: {
+    host: parsedUrl.hostname,
+    port: Number(parsedUrl.port) || 5432,
+    user: decodeURIComponent(parsedUrl.username),
+    password: decodeURIComponent(parsedUrl.password),
+    database: parsedUrl.pathname.split('/')[1],
+  },
+});

package/templates/scripts/gen-openapi.ts

@@ -3,11 +3,20 @@ import { DevToolsModule } from '@lark-apaas/fullstack-nestjs-core';
 
 import { AppModule } from '../server/app.module';
 
+/**
+ * 生成 OpenAPI 文档和客户端 SDK
+ *
+ * 此文件由 @lark-apaas/fullstack-cli 自动派生，请勿手动修改
+ * 每次运行 npm install 时会自动更新
+ */
 async function generateOpenApi() {
-  const app = await NestFactory.create(AppModule, {logger: false});
+  const app = await NestFactory.create(AppModule, { logger: false });
   const basePath = process.env.CLIENT_BASE_PATH;
-  app.setGlobalPrefix(basePath);
-  
+
+  if (basePath) {
+    app.setGlobalPrefix(basePath);
+  }
+
   await DevToolsModule.mount(app, {
     basePath,
     docsPath: '/api_docs',