@ai-partner-x/aiko-boot-cli 0.1.4

package/README.md

@@ -0,0 +1,187 @@
+## @ai-partner-x/aiko-boot-cli
+
+CLI 用来创建和扩展 aiko-boot 脚手架工程（monorepo：`api` / `admin` / `mobile` / `core`）。
+
+### 基本用法
+
+```bash
+# 在当前目录下新建一个完整脚手架（带 api/admin/mobile）
+aiko-boot create my-app --with-api --with-admin --with-mobile
+
+# 使用 pnpm script（假设 package.json 里配置了）
+pnpm aiko-boot create my-app --with-api --with-admin --with-mobile
+```
+
+> 说明：发布到 npm 后，推荐全局或在项目中安装 `@ai-partner-x/aiko-boot-cli`，然后直接运行 `aiko-boot ...`。
+
+---
+
+### 子命令一览
+
+- `create`：创建新的脚手架 monorepo
+- `add-app`：在现有脚手架中新增前端应用（`admin` / `mobile`）
+- `add-api`：在现有脚手架中新增后端服务（`api`）
+- `add-feature`：为指定后端服务增加特性组件（`redis` / `file` / `mq`）
+- `list`：查看当前脚手架配置（apps / apis / features）
+
+下面分别说明各命令的参数。
+
+---
+
+### `create` – 创建脚手架
+
+**语法：**
+
+```bash
+aiko-boot create [targetDir] [options]
+```
+
+**参数：**
+
+- `[targetDir]`（可选）  
+  目标目录，例如 `test7`。不传时会在交互里询问。
+
+**选项：**
+
+- `-n, --name <name>`：项目名 / scope，例如 `my-app`。  
+  - 不传时，会优先从 `targetDir` 推断（取目录名），否则通过交互询问。
+- `--empty`：仅创建空的 monorepo 结构（根 + `packages/`），不生成 `api/admin/mobile` 代码。
+- `--with-admin`：初始化时一起生成 admin 应用（`packages/admin`）。
+- `--with-mobile`：初始化时一起生成 mobile 应用（`packages/mobile`）。
+- `--with-api`：初始化时一起生成 api 服务端（`packages/api`）。
+- `--template-dir <dir>`：模板目录。  
+  - 不传时默认使用包内置模板：`templates/scaffold-default`。
+- `--dry-run`：只打印将要执行的操作，不写入任何文件。
+
+**示例：**
+
+```bash
+# 当前目录下创建 test7 脚手架，并包含 api/admin/mobile
+aiko-boot create test7 --with-api --with-admin --with-mobile
+
+# 只建空骨架
+aiko-boot create my-base --empty
+```
+
+---
+
+### `add-app` – 新增前端应用（admin / mobile）
+
+**语法：**
+
+```bash
+aiko-boot add-app [name] [options]
+```
+
+**参数：**
+
+- `[name]`（可选）  
+  新应用名称，例如 `admin`、`mobile-v2`。不传时会在交互中询问。
+
+**选项：**
+
+- `-t, --type <type>`：应用类型，`admin` | `mobile`。不传时会交互询问。
+- `--root <dir>`：脚手架根目录（包含 `.aiko-boot.json` 的目录），默认 `process.cwd()`。
+- `--template-dir <dir>`：模板根目录（开发时通常为 `scaffold`）。  
+  - 当前实现需要显式指定，否则会报错。
+- `--dry-run`：仅打印要执行的操作，不写入文件。
+
+**行为要点：**
+
+- 从 `templateDir/packages/<type>` 拷贝模板到 `rootDir/packages/<name>`。
+- 根据项目 `scope` 把包名改为 `@<scope>/<name>`，并替换模板中的 `@scaffold/*` 为 `@<scope>/*`。
+- 如果 `packages/core` 不存在，会从模板复制一份 core 包并重命名为 `@<scope>/core`。
+
+**示例：**
+
+```bash
+# 在现有脚手架根目录新增 admin 应用
+aiko-boot add-app admin -t admin --root . --template-dir scaffold
+
+# 新增 mobile-v2 应用
+aiko-boot add-app mobile-v2 -t mobile --template-dir scaffold
+```
+
+---
+
+### `add-api` – 新增后端服务
+
+**语法：**
+
+```bash
+aiko-boot add-api [name] [options]
+```
+
+**参数：**
+
+- `[name]`（可选）  
+  服务端名称，例如 `api`、`user-api`。不传时会交互询问。
+
+**选项：**
+
+- `--db <db>`：数据库类型，当前默认 `sqlite`（预留支持其他类型）。
+- `--root <dir>`：脚手架根目录，默认 `process.cwd()`。
+- `--template-dir <dir>`：模板根目录，用于找到 `packages/api` 模板。
+- `--dry-run`：仅打印操作计划，不写文件。
+
+**示例：**
+
+```bash
+# 为当前脚手架增加一个 user-api 服务
+aiko-boot add-api user-api --db sqlite --template-dir scaffold
+```
+
+---
+
+### `add-feature` – 为服务端增加特性组件
+
+**语法：**
+
+```bash
+aiko-boot add-feature --service <service> --feature <feature> [options]
+```
+
+**选项：**
+
+- `--service <service>`（必填）：目标服务端名称，例如 `api`、`user-api`。
+- `--feature <feature>`（必填）：特性类型，目前支持：`redis` | `file` | `mq`。
+- `--root <dir>`：脚手架根目录，默认 `process.cwd()`。
+- `--dry-run`：仅预览，不写文件。
+
+**示例：**
+
+```bash
+# 给 api 增加 redis 支持
+aiko-boot add-feature --service api --feature redis
+
+# 给 user-api 增加 mq 支持（dry-run）
+aiko-boot add-feature --service user-api --feature mq --dry-run
+```
+
+---
+
+### `list` – 查看当前脚手架配置
+
+**语法：**
+
+```bash
+aiko-boot list [options]
+```
+
+**选项：**
+
+- `--root <dir>`：脚手架根目录，默认 `process.cwd()`。
+
+**行为：**
+
+- 从指定根目录读取 `.aiko-boot.json`，打印：
+  - `scope`
+  - `apps`：`name [type] -> path`
+  - `apis`：`name [db=xxx] features=[...] -> path`
+
+**示例：**
+
+```bash
+aiko-boot list
+aiko-boot list --root ./test7
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[]): void;

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * aiko-boot CLI
+ *
+ * 顶层入口：注册子命令（create / add app / add api / add feature / list）。
+ */
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { registerCreateCommand } from './commands/init.js';
+import { registerAddAppCommand } from './commands/add-app.js';
+import { registerAddApiCommand } from './commands/add-api.js';
+import { registerAddFeatureCommand } from './commands/add-feature.js';
+import { registerListCommand } from './commands/list.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+export function runCli(argv = process.argv) {
+    const program = new Command();
+    program
+        .name('aiko-boot')
+        .description('Create and extend aiko-boot scaffold projects (monorepo: api, admin, mobile, core)')
+        .version(version);
+    // 注册子命令
+    registerCreateCommand(program);
+    registerAddAppCommand(program);
+    registerAddApiCommand(program);
+    registerAddFeatureCommand(program);
+    registerListCommand(program);
+    program.parse(argv);
+}
+runCli();

package/dist/commands/add-api.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+/**
+ * add api 命令：在现有脚手架中新增服务端工程（默认包含数据库）。
+ */
+export declare function registerAddApiCommand(program: Command): void;

package/dist/commands/add-api.js

@@ -0,0 +1,34 @@
+import { createAddApiUseCase } from '../usecases/add-api.usecase.js';
+import { createCliLogger } from '../core/logger.js';
+import { createPrompter } from '../core/prompts.js';
+/**
+ * add api 命令：在现有脚手架中新增服务端工程（默认包含数据库）。
+ */
+export function registerAddApiCommand(program) {
+    program
+        .command('add-api')
+        .argument('[name]', '服务端名称，例如 api、user-api')
+        .option('--db <db>', '数据库类型（预留：sqlite | postgres | mysql 等）', 'sqlite')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .option('--template-dir <dir>', '模板根目录（开发阶段通常为 ai-first-framework/scaffold）')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .description('在现有脚手架中新增服务端工程（自动包含数据库初始化逻辑）')
+        .action(async (name, options) => {
+        const logger = createCliLogger();
+        const prompter = createPrompter();
+        const usecase = createAddApiUseCase({ logger, prompter });
+        try {
+            await usecase.execute({
+                name,
+                db: options.db,
+                rootDir: options.root,
+                templateDir: options.templateDir,
+                dryRun: !!options.dryRun,
+            });
+        }
+        catch (err) {
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/add-app.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+/**
+ * add app 命令：在现有脚手架中新增前端应用（admin / mobile）。
+ */
+export declare function registerAddAppCommand(program: Command): void;

package/dist/commands/add-app.js

@@ -0,0 +1,34 @@
+import { createAddAppUseCase } from '../usecases/add-app.usecase.js';
+import { createCliLogger } from '../core/logger.js';
+import { createPrompter } from '../core/prompts.js';
+/**
+ * add app 命令：在现有脚手架中新增前端应用（admin / mobile）。
+ */
+export function registerAddAppCommand(program) {
+    program
+        .command('add-app')
+        .argument('[name]', '应用名称，例如 admin、mobile-v2')
+        .option('-t, --type <type>', '应用类型：admin | mobile')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .option('--template-dir <dir>', '模板根目录（开发阶段通常为 ai-first-framework/scaffold）')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .description('在现有脚手架中新增前端应用（admin / mobile）')
+        .action(async (name, options) => {
+        const logger = createCliLogger();
+        const prompter = createPrompter();
+        const usecase = createAddAppUseCase({ logger, prompter });
+        try {
+            await usecase.execute({
+                name,
+                type: options.type,
+                rootDir: options.root,
+                templateDir: options.templateDir,
+                dryRun: !!options.dryRun,
+            });
+        }
+        catch (err) {
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/add-feature.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+/**
+ * add feature 命令：给指定服务端增加特定组件（redis / file / mq）。
+ */
+export declare function registerAddFeatureCommand(program: Command): void;

package/dist/commands/add-feature.js

@@ -0,0 +1,32 @@
+import { createAddFeatureUseCase } from '../usecases/add-feature.usecase.js';
+import { createCliLogger } from '../core/logger.js';
+import { createPrompter } from '../core/prompts.js';
+/**
+ * add feature 命令：给指定服务端增加特定组件（redis / file / mq）。
+ */
+export function registerAddFeatureCommand(program) {
+    program
+        .command('add-feature')
+        .requiredOption('--service <service>', '目标服务端名称，例如 api、user-api')
+        .requiredOption('--feature <feature>', '特性类型：redis | file | mq | log（可扩展）')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .description('为指定服务端增加特性组件（redis、文件管理、消息队列等）')
+        .action(async (options) => {
+        const logger = createCliLogger();
+        const prompter = createPrompter();
+        const usecase = createAddFeatureUseCase({ logger, prompter });
+        try {
+            await usecase.execute({
+                serviceName: options.service,
+                feature: options.feature,
+                rootDir: options.root,
+                dryRun: !!options.dryRun,
+            });
+        }
+        catch (err) {
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+/**
+ * create 命令：创建新的脚手架 monorepo。
+ *
+ * 仅搭建参数和调用用例层的骨架，实际业务逻辑在 usecase 中实现。
+ */
+export declare function registerCreateCommand(program: Command): void;

package/dist/commands/init.js

@@ -0,0 +1,42 @@
+import { createInitUseCase } from '../usecases/init-scaffold.usecase.js';
+import { createCliLogger } from '../core/logger.js';
+import { createPrompter } from '../core/prompts.js';
+/**
+ * create 命令：创建新的脚手架 monorepo。
+ *
+ * 仅搭建参数和调用用例层的骨架，实际业务逻辑在 usecase 中实现。
+ */
+export function registerCreateCommand(program) {
+    program
+        .command('create')
+        .argument('[targetDir]', '目标目录（默认：当前目录下以项目名命名的文件夹）')
+        .option('-n, --name <name>', '项目名 / scope，例如 my-app')
+        .option('--empty', '仅创建空的 monorepo 结构，不包含 admin/mobile/api')
+        .option('--with-admin', '在初始化时创建 admin 应用')
+        .option('--with-mobile', '在初始化时创建 mobile 应用')
+        .option('--with-api', '在初始化时创建 api 服务端')
+        .option('--template-dir <dir>', '模板目录（默认：<cwd>/scaffold）')
+        .option('--dry-run', '仅显示将要执行的操作，不实际写入文件')
+        .description('创建一个新的 aiko-boot 脚手架 monorepo')
+        .action(async (targetDir, options) => {
+        const logger = createCliLogger();
+        const prompter = createPrompter();
+        const usecase = createInitUseCase({ logger, prompter });
+        try {
+            await usecase.execute({
+                targetDir,
+                name: options.name,
+                empty: !!options.empty,
+                withAdmin: !!options.withAdmin,
+                withMobile: !!options.withMobile,
+                withApi: !!options.withApi,
+                templateDir: options.templateDir,
+                dryRun: !!options.dryRun,
+            });
+        }
+        catch (err) {
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+/**
+ * list 命令：列出当前脚手架中的 apps / apis / features。
+ * 仅作为演示配置文件结构的命令，方便用户查看当前状态。
+ */
+export declare function registerListCommand(program: Command): void;

package/dist/commands/list.js

@@ -0,0 +1,36 @@
+import { createCliLogger } from '../core/logger.js';
+import { loadProjectConfig } from '../core/project-config.js';
+/**
+ * list 命令：列出当前脚手架中的 apps / apis / features。
+ * 仅作为演示配置文件结构的命令，方便用户查看当前状态。
+ */
+export function registerListCommand(program) {
+    program
+        .command('list')
+        .option('--root <dir>', '脚手架根目录（默认：当前工作目录）')
+        .description('列出当前脚手架中的应用、服务端和特性')
+        .action(async (options) => {
+        const logger = createCliLogger();
+        const rootDir = options.root ?? process.cwd();
+        try {
+            const config = await loadProjectConfig(rootDir);
+            if (!config) {
+                logger.info('当前目录似乎不是 aiko-boot 脚手架根目录（未找到 .aiko-boot.json）。');
+                return;
+            }
+            logger.info(`scope: ${config.scope ?? '(unknown)'}`);
+            logger.info('apps:');
+            for (const app of config.apps ?? []) {
+                logger.info(`  - ${app.name} [${app.type}] -> ${app.path}`);
+            }
+            logger.info('apis:');
+            for (const api of config.apis ?? []) {
+                logger.info(`  - ${api.name} [db=${api.db}] features=[${(api.features ?? []).join(', ')}] -> ${api.path}`);
+            }
+        }
+        catch (err) {
+            logger.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/core/framework-version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 获取脚手架生成时使用的 @ai-partner-x/* 依赖版本范围。
+ *
+ * 规则：
+ * - 若设置了 AI_PARTNER_FRAMEWORK_VERSION，则优先使用（便于本地测试/回滚）。
+ * - 否则默认使用当前 aiko-boot-cli 自身的版本号，并加上 ^，确保小版本/补丁版本兼容升级。
+ */
+export declare function getFrameworkRegistryVersion(): Promise<string>;

package/dist/core/framework-version.js

@@ -0,0 +1,40 @@
+import fs from 'fs-extra';
+let cached = null;
+/**
+ * 获取脚手架生成时使用的 @ai-partner-x/* 依赖版本范围。
+ *
+ * 规则：
+ * - 若设置了 AI_PARTNER_FRAMEWORK_VERSION，则优先使用（便于本地测试/回滚）。
+ * - 否则默认使用当前 aiko-boot-cli 自身的版本号，并加上 ^，确保小版本/补丁版本兼容升级。
+ */
+export async function getFrameworkRegistryVersion() {
+    if (cached)
+        return cached;
+    const fromEnv = process.env.AI_PARTNER_FRAMEWORK_VERSION;
+    if (fromEnv && typeof fromEnv === 'string') {
+        cached = fromEnv;
+        return fromEnv;
+    }
+    // dist/* 下运行时：package.json 一定在 dist/..（或 dist/**/../..）能被定位到
+    // 这里从当前模块路径向上寻找 package.json，避免硬编码版本号。
+    const candidateUrls = [
+        new URL('../../package.json', import.meta.url),
+        new URL('../package.json', import.meta.url),
+        new URL('../../../package.json', import.meta.url),
+    ];
+    for (const url of candidateUrls) {
+        try {
+            const pkg = await fs.readJson(url);
+            if (pkg?.version && typeof pkg.version === 'string') {
+                cached = `^${pkg.version}`;
+                return cached;
+            }
+        }
+        catch {
+            // ignore and try next
+        }
+    }
+    // 最后兜底：避免脚手架中断（但强烈建议不要依赖这个兜底）
+    cached = '^0.1.0';
+    return cached;
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,6 @@
+export type Logger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export declare function createCliLogger(): Logger;

package/dist/core/logger.js

@@ -0,0 +1,16 @@
+export function createCliLogger() {
+    return {
+        info: (msg) => {
+            // eslint-disable-next-line no-console
+            console.log(msg);
+        },
+        warn: (msg) => {
+            // eslint-disable-next-line no-console
+            console.warn(msg);
+        },
+        error: (msg) => {
+            // eslint-disable-next-line no-console
+            console.error(msg);
+        },
+    };
+}

package/dist/core/project-config.d.ts

@@ -0,0 +1,21 @@
+export type AikoAppConfig = {
+    name: string;
+    type: 'admin' | 'mobile' | string;
+    path: string;
+};
+export type AikoApiConfig = {
+    name: string;
+    path: string;
+    db: string;
+    features?: string[];
+};
+export type AikoProjectConfig = {
+    version: number;
+    scope?: string;
+    packageManager?: 'pnpm' | 'npm' | 'yarn';
+    apps?: AikoAppConfig[];
+    apis?: AikoApiConfig[];
+};
+export declare function getProjectConfigPath(rootDir: string): string;
+export declare function loadProjectConfig(rootDir: string): Promise<AikoProjectConfig | null>;
+export declare function saveProjectConfig(rootDir: string, config: AikoProjectConfig): Promise<void>;

package/dist/core/project-config.js

@@ -0,0 +1,17 @@
+import path from 'path';
+import fs from 'fs-extra';
+const CONFIG_FILE_NAME = '.aiko-boot.json';
+export function getProjectConfigPath(rootDir) {
+    return path.join(rootDir, CONFIG_FILE_NAME);
+}
+export async function loadProjectConfig(rootDir) {
+    const configPath = getProjectConfigPath(rootDir);
+    if (!(await fs.pathExists(configPath))) {
+        return null;
+    }
+    return fs.readJson(configPath);
+}
+export async function saveProjectConfig(rootDir, config) {
+    const configPath = getProjectConfigPath(rootDir);
+    await fs.writeJson(configPath, config, { spaces: 2 });
+}

package/dist/core/prompts.d.ts

@@ -0,0 +1,5 @@
+export type Prompter = {
+    input: (question: string, defaultValue?: string) => Promise<string>;
+    confirm: (question: string, defaultValue?: boolean) => Promise<boolean>;
+};
+export declare function createPrompter(): Prompter;

package/dist/core/prompts.js

@@ -0,0 +1,43 @@
+import readline from 'readline';
+export function createPrompter() {
+    return {
+        async input(question, defaultValue) {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const suffix = defaultValue !== undefined ? ` (${defaultValue})` : '';
+            return new Promise((resolve) => {
+                rl.question(`${question}${suffix}: `, (answer) => {
+                    rl.close();
+                    const trimmed = answer.trim();
+                    if (!trimmed && defaultValue !== undefined) {
+                        resolve(defaultValue);
+                    }
+                    else {
+                        resolve(trimmed);
+                    }
+                });
+            });
+        },
+        async confirm(question, defaultValue = false) {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const hint = defaultValue ? 'Y/n' : 'y/N';
+            return new Promise((resolve) => {
+                rl.question(`${question} [${hint}]: `, (answer) => {
+                    rl.close();
+                    const lower = answer.trim().toLowerCase();
+                    if (!lower) {
+                        resolve(defaultValue);
+                    }
+                    else {
+                        resolve(lower === 'y' || lower === 'yes');
+                    }
+                });
+            });
+        },
+    };
+}

package/dist/core/template-utils.d.ts

@@ -0,0 +1 @@
+export declare function replaceScopeInDir(dir: string, fromScope: string, toScope: string): Promise<void>;

package/dist/core/template-utils.js

@@ -0,0 +1,42 @@
+import path from 'path';
+import fs from 'fs-extra';
+const TEXT_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.json',
+    '.mjs',
+    '.cjs',
+    '.md',
+    '.css',
+    '.html',
+]);
+export async function replaceScopeInDir(dir, fromScope, toScope) {
+    async function walk(current) {
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+                    continue;
+                }
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (!TEXT_EXTENSIONS.has(ext))
+                    continue;
+                let content = await fs.readFile(full, 'utf-8');
+                const before = content;
+                const from = `@${fromScope}/`;
+                const to = `@${toScope}/`;
+                content = content.replaceAll(from, to);
+                if (content !== before) {
+                    await fs.writeFile(full, content, 'utf-8');
+                }
+            }
+        }
+    }
+    await walk(dir);
+}

package/dist/core/workspace.d.ts

@@ -0,0 +1,10 @@
+import { type AikoProjectConfig } from './project-config.js';
+export declare function ensurePnpmWorkspace(rootDir: string): Promise<void>;
+export declare function withProjectConfig(rootDir: string, updater: (config: AikoProjectConfig) => AikoProjectConfig | void): Promise<AikoProjectConfig>;
+/**
+ * 根据 .aiko-boot.json 的配置，同步根目录下的 package.json：
+ * - 补充 name/version/private
+ * - 生成常用 scripts（dev / build / lint / dev:api 等）
+ * - 便于后续在根目录直接运行 pnpm 脚本
+ */
+export declare function syncRootPackageJson(rootDir: string): Promise<void>;