@lark-apaas/fullstack-cli 0.1.0-alpha.1 → 0.1.0-alpha.10

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.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const command = process.argv[2];
+const distPath = path.join(__dirname, '..', 'dist');
+
+async function main() {
+  try {
+    switch (command) {
+      case 'gen-db-schema': {
+        const modulePath = path.join(distPath, 'commands', 'gen-db-schema.js');
+        const { run } = await import(modulePath);
+        await run();
+        break;
+      }
+      case 'sync':
+      case 'postinstall': {
+        // 调用原有的 sync-scripts.js (CommonJS)
+        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);
+    console.error(error.stack);
+    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);
   }
@@ -27,8 +26,7 @@ async function main() {
     console.log('[fullstack-cli] Starting sync...');
 
     // 加载配置文件（从 dist 目录加载编译后的配置）
-    const configPath = path.join(pluginRoot, 'dist', 'postinstall.config.js');
-    const { default: config } = await import(`file://${configPath}`);
+    const { default: config } = await import('../dist/postinstall.config.js');
 
     if (!config || !config.sync) {
       console.warn('[fullstack-cli] No sync configuration found');

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,90 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+// 加载 .env 配置
+import { config as loadEnv } from 'dotenv';
+// 创建 require 函数来加载 CommonJS 模块
+const require = createRequire(import.meta.url);
+/**
+ * 生成数据库 schema
+ *
+ * 环境变量配置：
+ * - SUDA_DATABASE_URL: 数据库连接 URL（必需）
+ * - DB_SCHEMA_OUTPUT: schema 输出路径，默认 'server/database/schema.ts'
+ * - DRIZZLE_SCHEMA_FILTER: schema 过滤器，逗号分隔
+ * - DRIZZLE_TABLES_FILTER: 表过滤器，逗号分隔，默认 '*'
+ */
+export async function run() {
+    // 加载用户项目的 .env 文件
+    const envPath = path.resolve(process.cwd(), '.env');
+    if (fs.existsSync(envPath)) {
+        loadEnv({ path: envPath });
+        console.log('[gen-db-schema] ✓ Loaded .env file');
+    }
+    const databaseUrl = process.env.SUDA_DATABASE_URL;
+    if (!databaseUrl) {
+        console.error('[gen-db-schema] Error: SUDA_DATABASE_URL environment variable is required');
+        console.error('[gen-db-schema] Please set it in .env file or pass it as environment variable');
+        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}`);
+    // 获取当前文件所在目录（ESM 方式）
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    // 使用 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}`);
+    // 后处理 schema（使用 CommonJS require 方式加载）
+    try {
+        const { postprocessDrizzleSchema } = require('@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 failed:', error instanceof Error ? error.message : String(error));
+    }
+    // 清理临时文件
+    if (fs.existsSync(OUT_DIR)) {
+        fs.rmSync(OUT_DIR, { recursive: true, force: true });
+    }
+    console.log('[gen-db-schema] ✓ Complete');
+}

package/dist/postinstall.config.js

@@ -12,23 +12,23 @@ const config = {
             type: 'directory',
             overwrite: true,
         },
-        // 2. 追加内容到 .gitignore
-        {
-            from: 'templates/.gitignore.append',
-            to: '.gitignore',
-            type: 'append',
-        },
-        // 3. 派生 server/type.ts 文件（总是覆盖）
-        {
-            from: 'templates/server/type.ts',
-            to: 'server/type.ts',
-            type: 'file',
-        },
+        // // 2. 追加内容到 .gitignore
+        // {
+        //   from: 'templates/.gitignore.append',
+        //   to: '.gitignore',
+        //   type: 'append',
+        // },
+        // // 3. 派生 server/type.ts 文件（总是覆盖）
+        // {
+        //   from: 'templates/server/type.ts',
+        //   to: 'server/type.ts',
+        //   type: 'file',
+        // },
     ],
     // 文件权限设置
     permissions: {
-        // 所有 .sh 文件设置为可执行
-        '**/*.sh': 0o755,
+    // 所有 .sh 文件设置为可执行
+    // '**/*.sh': 0o755,
     },
 };
 export default config;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "description": "CLI tool for fullstack template management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": "./bin/cli.mjs",
   "files": [
     "dist",
     "templates",
@@ -27,6 +28,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@lark-apaas/devtool-kits": "^1.0.0",
+    "dotenv": "^16.0.0",
+    "drizzle-kit": "0.31.5"
+  },
   "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 parsedUrl = new URL(process.env.SUDA_DATABASE_URL || '');
+const schemaFilter = parsedUrl.searchParams.get('schema')?.split(',') ?? [];
+
+const config = {
+  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],
+  },
+}
+export default defineConfig(config);

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',

package/dist/config/postinstall.config.d.ts

@@ -1,22 +0,0 @@
-/**
- * fullstack-cli 派生配置
- * 定义哪些文件/目录需要同步到用户项目
- */
-export interface SyncRule {
-    /** 源文件/目录路径（相对于插件根目录） */
-    from: string;
-    /** 目标文件/目录路径（相对于用户项目根目录） */
-    to: string;
-    /** 同步类型 */
-    type: 'directory' | 'file' | 'append';
-    /** 是否覆盖已存在的文件（仅 directory 和 file 类型有效） */
-    overwrite?: boolean;
-}
-export interface PostinstallConfig {
-    /** 派生规则 */
-    sync: SyncRule[];
-    /** 文件权限设置 */
-    permissions?: Record<string, number>;
-}
-declare const config: PostinstallConfig;
-export default config;

package/dist/config/postinstall.config.js

@@ -1,28 +0,0 @@
-/**
- * fullstack-cli 派生配置
- * 定义哪些文件/目录需要同步到用户项目
- */
-const config = {
-    // 派生规则
-    sync: [
-        // 1. 派生 scripts 目录（总是覆盖）
-        {
-            from: 'templates/scripts',
-            to: 'scripts',
-            type: 'directory',
-            overwrite: true,
-        },
-        // 2. 追加内容到 .gitignore
-        {
-            from: 'templates/.gitignore.append',
-            to: '.gitignore',
-            type: 'append',
-        },
-    ],
-    // 文件权限设置
-    permissions: {
-        // 所有 .sh 文件设置为可执行
-        '**/*.sh': 0o755,
-    },
-};
-export default config;

package/templates/scripts/gen-db-schema.ts

@@ -1,48 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { postprocessDrizzleSchema } from '@lark-apaas/devtool-kits';
-
-const OUT_DIR = path.resolve(process.cwd(), 'server/database/.introspect');
-const SCHEMA_FILE = path.resolve(process.cwd(), 'server/database/schema.ts');
-
-function run(): void {
-  const args = process.argv.slice(2);
-  const spawnArgs = ['--yes', 'drizzle-kit', 'introspect', '--config', 'drizzle.config.ts', ...args];
-
-  const result = spawnSync('npx', spawnArgs, { stdio: 'inherit' });
-  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);
-  }
-
-  const generatedSchema = path.join(OUT_DIR, 'schema.ts');
-  if (!fs.existsSync(generatedSchema)) {
-    console.warn('[gen-db-schema] schema.ts not generated');
-    process.exit(1);
-  }
-
-  fs.mkdirSync(path.dirname(SCHEMA_FILE), { recursive: true });
-  fs.copyFileSync(generatedSchema, SCHEMA_FILE);
-
-  try {
-    const stats = postprocessDrizzleSchema(SCHEMA_FILE);
-    if (stats?.unmatchedUnknown?.length) {
-      console.warn('[gen-db-schema] Unmatched custom types detected');
-    }
-  } catch (error) {
-    console.warn('[gen-db-schema] postprocess failed:', error);
-  }
-
-  if (fs.existsSync(OUT_DIR)) {
-    fs.rmSync(OUT_DIR, { recursive: true, force: true });
-  }
-}
-
-if (require.main === module) {
-  run();
-}