feat: refactor dev into command group with dynamic custom subcommands

Restructure dev/dev:web/dev:celery into a `dev` command group (dev web,
dev celery), and support user-defined dev commands from project .fba.json
`devs` config. Custom commands are dynamically registered as subcommands
and visible via `fba dev -h`.

Made-with: Cursor

Author: yuWorm

src/commands/dev.ts

@@ -1,13 +1,14 @@
-// dev.ts — dev / dev:web / dev:celery 命令
+// dev.ts — dev 命令组：server / web / celery / 自定义
 import * as clack from '@clack/prompts'
 import chalk from 'chalk'
 import { existsSync } from 'fs'
-import { join } from 'path'
+import { join, resolve } from 'path'
 import { readProjectConfig, getInfraDir } from '../lib/config.js'
 import { requireProjectDir, requireBackendDir, requireFrontendDir, warn } from '../lib/errors.js'
 import { isComposeRunning, composeUp } from '../lib/docker.js'
 import { runInherited } from '../lib/process.js'
 import { t } from '../lib/i18n.js'
+import type { DevEntry } from '../types/config.js'
 
 /**
  * fba dev — 启动后端
@@ -91,3 +92,21 @@ export async function devCeleryAction(subcommand: string, options: { project?: s
   const exitCode = await runInherited('uv', ['run', 'fba', 'celery', subcommand], backendDir)
   process.exit(exitCode)
 }
+
+/**
+ * fba dev <name> — 运行自定义开发命令
+ */
+export async function devCustomAction(
+  name: string,
+  entry: DevEntry,
+  options: { project?: string },
+) {
+  const projectDir = requireProjectDir(options.project)
+  const cwd = entry.pwd ? resolve(projectDir, entry.pwd) : projectDir
+
+  console.log(chalk.cyan(`\n  ${t('devCustomStarting')} ${name}...\n`))
+
+  const [cmd, ...args] = entry.cmd.trim().split(/\s+/) as [string, ...string[]]
+  const exitCode = await runInherited(cmd, args, cwd, { env: entry.envs })
+  process.exit(exitCode)
+}

src/index.ts

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 // index.ts — FBA CLI 入口：Commander 命令路由
-import { readFileSync } from 'fs'
+import { readFileSync, existsSync } from 'fs'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { Command } from 'commander'
 import chalk from 'chalk'
-import { readGlobalConfig } from './lib/config.js'
+import { readGlobalConfig, readProjectConfig, resolveProjectDir } from './lib/config.js'
 import { initI18nFromConfig, t } from './lib/i18n.js'
 
 const currentDir = dirname(fileURLToPath(import.meta.url))
@@ -55,10 +55,10 @@ program
     await addAction()
   })
 
-// ─── dev ───
-program
+// ─── dev (command group) ───
+const devCmd = program
   .command('dev')
-  .description(t('cmdDev'))
+  .description(t('cmdDevGroup'))
   .option('--host <host>', t('optHost'), '127.0.0.1')
   .option('--port <port>', t('optPort'))
   .option('--no-reload', t('optNoReload'))
@@ -68,9 +68,8 @@ program
     await devAction({ ...options, project: program.opts().project })
   })
 
-// ─── dev:web ───
-program
-  .command('dev:web')
+devCmd
+  .command('web')
   .description(t('cmdDevWeb'))
   .option('--host <host>', t('optHost'))
   .option('--port <port>', t('optPort'))
@@ -79,15 +78,43 @@ program
     await devWebAction({ ...options, project: program.opts().project })
   })
 
-// ─── dev:celery ───
-program
-  .command('dev:celery <subcommand>')
+devCmd
+  .command('celery <subcommand>')
   .description(t('cmdDevCelery'))
   .action(async (subcommand) => {
     const { devCeleryAction } = await import('./commands/dev.js')
     await devCeleryAction(subcommand, { project: program.opts().project })
   })
 
+// Dynamic dev subcommands from project .fba.json
+{
+  const preProject = (() => {
+    const args = process.argv.slice(2)
+    for (let i = 0; i < args.length; i++) {
+      if ((args[i] === '-p' || args[i] === '--project') && args[i + 1]) return args[i + 1]
+      if (args[i]?.startsWith('--project=')) return args[i]!.slice('--project='.length)
+    }
+    return undefined
+  })()
+  const projectDir = resolveProjectDir(preProject)
+  if (projectDir && existsSync(projectDir)) {
+    const projectConfig = readProjectConfig(projectDir)
+    if (projectConfig.devs) {
+      const builtins = new Set(['web', 'celery', 'help'])
+      for (const [name, entry] of Object.entries(projectConfig.devs)) {
+        if (builtins.has(name)) continue
+        devCmd
+          .command(name)
+          .description(entry.desc ?? entry.cmd)
+          .action(async () => {
+            const { devCustomAction } = await import('./commands/dev.js')
+            await devCustomAction(name, entry, { project: program.opts().project })
+          })
+      }
+    }
+  }
+}
+
 // ─── plugin ───
 const pluginCmd = program
   .command('plugin')

src/lib/i18n.ts

@@ -205,6 +205,7 @@ const messages = {
     devStartingBackend: "正在启动后端服务器，端口:",
     devStartingFrontend: "正在启动前端开发服务器...",
     devStartingCelery: "正在启动 Celery",
+    devCustomStarting: "正在启动",
     invalidSubcommand: "无效子命令",
     validOptions: "有效选项",
 
@@ -253,6 +254,7 @@ const messages = {
     cliDescription:
       "创建、管理和运行 fastapi-best-architecture 项目的 Super CLI 工具",
     cmdCreate: "创建新的 FBA 项目（引导流程）",
+    cmdDevGroup: "开发服务器命令",
     cmdDev: "启动后端开发服务器",
     cmdDevWeb: "启动前端开发服务器",
     cmdDevCelery: "启动 Celery 服务 (worker | beat | flower)",
@@ -478,6 +480,7 @@ const messages = {
     devStartingBackend: "Starting backend server on port",
     devStartingFrontend: "Starting frontend dev server...",
     devStartingCelery: "Starting Celery",
+    devCustomStarting: "Starting",
     invalidSubcommand: "Invalid subcommand",
     validOptions: "Valid options",
 
@@ -523,6 +526,7 @@ const messages = {
     cliDescription:
       "Super CLI tool for creating, managing, and running fastapi-best-architecture projects",
     cmdCreate: "Create a new FBA project (guided flow)",
+    cmdDevGroup: "Development server commands",
     cmdDev: "Start backend development server",
     cmdDevWeb: "Start frontend development server",
     cmdDevCelery: "Start Celery service (worker | beat | flower)",

src/lib/process.ts

@@ -112,20 +112,24 @@ export async function runInherited(
   cmd: string,
   args: string[] = [],
   cwd?: string,
+  options?: { env?: Record<string, string> },
 ): Promise<number> {
-  // 保存 stdin 的 raw mode 状态，并恢复为正常模式
   const wasRaw = process.stdin.isRaw
   if (wasRaw && process.stdin.isTTY) {
     process.stdin.setRawMode(false)
   }
 
   try {
-    const result = await execa(cmd, args, { cwd, stdio: 'inherit', reject: false })
+    const result = await execa(cmd, args, {
+      cwd,
+      stdio: 'inherit',
+      reject: false,
+      env: options?.env,
+    })
     return result.exitCode ?? 1
   } catch {
     return 1
   } finally {
-    // 恢复 stdin raw mode 状态
     if (wasRaw && process.stdin.isTTY) {
       process.stdin.setRawMode(true)
     }

src/types/config.ts

@@ -16,6 +16,13 @@ export interface ProjectEntry {
   createdAt: string
 }
 
+export interface DevEntry {
+  cmd: string
+  pwd?: string
+  envs?: Record<string, string>
+  desc?: string
+}
+
 export interface ProjectConfig {
   name: string
   backend_name: string
@@ -25,6 +32,7 @@ export interface ProjectConfig {
   infra: boolean
   infra_services: string[]
   db_type?: DatabaseType
+  devs?: Record<string, DevEntry>
 }
 
 export const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {