@zhin.js/scaffold-wizard 1.1.0 → 1.1.2

package/src/database-definitions.ts

@@ -0,0 +1,336 @@
+import type { DatabaseConfig } from './types.js';
+
+export type DatabaseDialect = DatabaseConfig['dialect'];
+
+export interface DatabaseDriverDefinition {
+  readonly package: string;
+  readonly version: string;
+}
+
+export interface DatabaseDialectDefinition {
+  readonly dialect: DatabaseDialect;
+  readonly name: string;
+  readonly description: string;
+  /** Concrete service version covered by the repository's live acceptance tests. */
+  readonly verifiedServer: string;
+  readonly driver?: DatabaseDriverDefinition;
+  readonly schema: Readonly<Record<string, unknown>>;
+}
+
+type SchemaIssueKind = 'env_missing' | 'invalid';
+
+export interface DatabaseSchemaIssue {
+  readonly kind: SchemaIssueKind;
+  readonly path: string;
+  readonly message: string;
+  readonly envKey?: string;
+}
+
+const text = (defaultValue?: string, extras: Record<string, unknown> = {}) => ({
+  type: 'string',
+  minLength: 1,
+  ...(defaultValue === undefined ? {} : { default: defaultValue }),
+  ...extras,
+});
+
+const port = (defaultValue: number) => ({
+  type: 'integer',
+  minimum: 1,
+  maximum: 65535,
+  default: defaultValue,
+});
+
+export const DATABASE_DIALECT_DEFINITIONS: readonly DatabaseDialectDefinition[] = Object.freeze([
+  {
+    dialect: 'sqlite',
+    name: 'SQLite',
+    description: '推荐，零配置，适合单机 Bot',
+    verifiedServer: 'Node.js 内置 node:sqlite（Node.js 22.5+）',
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['dialect'],
+      properties: {
+        dialect: { const: 'sqlite' },
+        filename: text('./data/bot.db'),
+        mode: { type: 'string', enum: ['wal', 'delete', 'memory'], default: 'wal' },
+      },
+    },
+  },
+  {
+    dialect: 'mysql',
+    name: 'MySQL',
+    description: '关系型数据库',
+    verifiedServer: 'MySQL 8.4 LTS',
+    driver: { package: 'mysql2', version: '^3.23.2' },
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['dialect'],
+      properties: {
+        dialect: { const: 'mysql' },
+        host: text('127.0.0.1'),
+        port: port(3306),
+        user: text('root'),
+        password: { type: 'string' },
+        database: text('zhin_bot'),
+      },
+    },
+  },
+  {
+    dialect: 'pg',
+    name: 'PostgreSQL',
+    description: '关系型数据库，方言名为 pg',
+    verifiedServer: 'PostgreSQL 17',
+    driver: { package: 'pg', version: '^8.22.0' },
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['dialect'],
+      properties: {
+        dialect: { const: 'pg' },
+        host: text('127.0.0.1'),
+        port: port(5432),
+        user: text('postgres'),
+        password: { type: 'string' },
+        database: text('zhin_bot'),
+      },
+    },
+  },
+  {
+    dialect: 'mongodb',
+    name: 'MongoDB',
+    description: '文档数据库',
+    verifiedServer: 'MongoDB 8',
+    driver: { package: 'mongodb', version: '^7.5.0' },
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['dialect', 'url', 'dbName'],
+      properties: {
+        dialect: { const: 'mongodb' },
+        url: text('mongodb://127.0.0.1:27017', { pattern: '^mongodb(?:\\+srv)?://' }),
+        dbName: text('zhin_bot'),
+      },
+    },
+  },
+  {
+    dialect: 'redis',
+    name: 'Redis',
+    description: '键值数据库',
+    verifiedServer: 'Redis 8',
+    driver: { package: 'redis', version: '^6.1.0' },
+    schema: {
+      type: 'object',
+      additionalProperties: true,
+      required: ['dialect'],
+      properties: {
+        dialect: { const: 'redis' },
+        socket: {
+          type: 'object',
+          additionalProperties: true,
+          required: ['host', 'port'],
+          properties: {
+            host: text('127.0.0.1'),
+            port: port(6379),
+          },
+        },
+        password: { type: 'string' },
+        database: { type: 'integer', minimum: 0, default: 0 },
+      },
+    },
+  },
+  {
+    dialect: 'memory',
+    name: 'Memory',
+    description: '仅进程内，适合测试，不持久化',
+    verifiedServer: 'Zhin 内置实现',
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['dialect'],
+      properties: { dialect: { const: 'memory' } },
+    },
+  },
+]);
+
+const definitions = new Map(DATABASE_DIALECT_DEFINITIONS.map((definition) => [definition.dialect, definition]));
+
+export function getDatabaseDialectDefinition(dialect: string): DatabaseDialectDefinition | undefined {
+  return definitions.get(dialect as DatabaseDialect);
+}
+
+export function databaseChoiceLabel(definition: DatabaseDialectDefinition): string {
+  const driver = definition.driver
+    ? `；驱动 ${definition.driver.package} ${definition.driver.version}`
+    : '';
+  return `${definition.name}（${definition.description}；当前支持/实机验证 ${definition.verifiedServer}${driver}）`;
+}
+
+function expandEnvReferences(
+  input: string,
+  path: string,
+  env: Readonly<Record<string, string | undefined>>,
+  issues: DatabaseSchemaIssue[],
+): string {
+  let output = '';
+  let index = 0;
+  while (index < input.length) {
+    const start = input.indexOf('${', index);
+    if (start < 0) break;
+    let cursor = start + 2;
+    const first = input[cursor];
+    if (first === undefined || !isEnvKeyStart(first)) {
+      output += input.slice(index, start + 1);
+      index = start + 1;
+      continue;
+    }
+    cursor += 1;
+    while (cursor < input.length && isEnvKeyCharacter(input[cursor]!)) cursor += 1;
+    const key = input.slice(start + 2, cursor);
+    let fallback: string | undefined;
+    if (input[cursor] === ':' && (input[cursor + 1] === '-' || input[cursor + 1] === '=')) {
+      const close = input.indexOf('}', cursor + 2);
+      if (close < 0) {
+        output += input.slice(index, start + 1);
+        index = start + 1;
+        continue;
+      }
+      fallback = input.slice(cursor + 2, close);
+      cursor = close;
+    }
+    if (input[cursor] !== '}') {
+      output += input.slice(index, start + 1);
+      index = start + 1;
+      continue;
+    }
+    output += input.slice(index, start);
+    const resolved = env[key];
+    if ((resolved === undefined || resolved === '') && fallback !== undefined) {
+      output += fallback;
+    } else if (resolved === undefined) {
+      issues.push({
+        kind: 'env_missing',
+        path,
+        envKey: key,
+        message: `环境变量 ${key} 未设置（${path}）`,
+      });
+    } else {
+      output += resolved;
+    }
+    index = cursor + 1;
+  }
+  return output + input.slice(index);
+}
+
+function isEnvKeyStart(character: string): boolean {
+  return (character >= 'A' && character <= 'Z')
+    || (character >= 'a' && character <= 'z')
+    || character === '_';
+}
+
+function isEnvKeyCharacter(character: string): boolean {
+  return isEnvKeyStart(character) || (character >= '0' && character <= '9');
+}
+
+function validateValue(
+  schema: Record<string, unknown>,
+  rawValue: unknown,
+  path: string,
+  env: Readonly<Record<string, string | undefined>>,
+  issues: DatabaseSchemaIssue[],
+): void {
+  let value = rawValue;
+  if (typeof value === 'string') {
+    const before = issues.length;
+    value = expandEnvReferences(value, path, env, issues);
+    if (issues.length > before) return;
+  }
+
+  if ('const' in schema && value !== schema.const) {
+    issues.push({ kind: 'invalid', path, message: `${path} 必须是 ${JSON.stringify(schema.const)}` });
+    return;
+  }
+  const type = schema.type;
+  if (type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      issues.push({ kind: 'invalid', path, message: `${path} 必须是对象` });
+      return;
+    }
+    const record = value as Record<string, unknown>;
+    const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(record)) {
+        if (!(key in properties)) {
+          issues.push({ kind: 'invalid', path: `${path}.${key}`, message: `${path}.${key} 不是受支持的配置项` });
+        }
+      }
+    }
+    for (const required of (schema.required ?? []) as string[]) {
+      if (!(required in record) || record[required] === undefined || record[required] === null) {
+        issues.push({ kind: 'invalid', path: `${path}.${required}`, message: `${path}.${required} 不能为空` });
+      }
+    }
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (record[key] !== undefined) validateValue(propertySchema, record[key], `${path}.${key}`, env, issues);
+    }
+    return;
+  }
+  if (type === 'string') {
+    if (typeof value !== 'string') {
+      issues.push({ kind: 'invalid', path, message: `${path} 必须是字符串` });
+      return;
+    }
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      issues.push({ kind: 'invalid', path, message: `${path} 不能为空` });
+    }
+    if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern, 'u').test(value)) {
+      issues.push({ kind: 'invalid', path, message: `${path} 格式无效` });
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+      issues.push({ kind: 'invalid', path, message: `${path} 必须是 ${schema.enum.join('、')} 之一` });
+    }
+    return;
+  }
+  if (type === 'integer') {
+    const numeric = typeof value === 'number'
+      ? value
+      : typeof value === 'string' && /^\d+$/u.test(value.trim())
+        ? Number(value.trim())
+        : Number.NaN;
+    if (!Number.isInteger(numeric)) {
+      issues.push({ kind: 'invalid', path, message: `${path} 必须是整数` });
+      return;
+    }
+    if (typeof schema.minimum === 'number' && numeric < schema.minimum) {
+      issues.push({ kind: 'invalid', path, message: `${path} 不能小于 ${schema.minimum}` });
+    }
+    if (typeof schema.maximum === 'number' && numeric > schema.maximum) {
+      issues.push({ kind: 'invalid', path, message: `${path} 不能大于 ${schema.maximum}` });
+    }
+  }
+}
+
+export function validateDatabaseConfig(
+  config: unknown,
+  env: Readonly<Record<string, string | undefined>> = {},
+): readonly DatabaseSchemaIssue[] {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return [{ kind: 'invalid', path: 'database', message: 'database 必须是对象' }];
+  }
+  const dialect = (config as Record<string, unknown>).dialect;
+  if (typeof dialect !== 'string') {
+    return [{ kind: 'invalid', path: 'database.dialect', message: 'database.dialect 不能为空' }];
+  }
+  const definition = getDatabaseDialectDefinition(dialect);
+  if (!definition) {
+    return [{
+      kind: 'invalid',
+      path: 'database.dialect',
+      message: `不支持的数据库方言 ${JSON.stringify(dialect)}`,
+    }];
+  }
+  const issues: DatabaseSchemaIssue[] = [];
+  validateValue(definition.schema as Record<string, unknown>, config, 'database', env, issues);
+  return Object.freeze(issues);
+}

package/src/database.ts

@@ -1,5 +1,31 @@
 import inquirer from 'inquirer';
 import { DatabaseConfig } from './types.js';
+import {
+  DATABASE_DIALECT_DEFINITIONS,
+  databaseChoiceLabel,
+  getDatabaseDialectDefinition,
+  validateDatabaseConfig,
+  type DatabaseDialect,
+} from './database-definitions.js';
+
+function schemaDefault(dialect: DatabaseDialect, ...path: string[]): unknown {
+  let schema = getDatabaseDialectDefinition(dialect)?.schema as Record<string, unknown> | undefined;
+  for (const segment of path) {
+    const properties = schema?.properties as Record<string, Record<string, unknown>> | undefined;
+    schema = properties?.[segment];
+  }
+  return schema?.default;
+}
+
+function parseIntegerInput(input: unknown, minimum: number, maximum = Number.MAX_SAFE_INTEGER): number | string {
+  const raw = String(input).trim();
+  if (!/^\d+$/u.test(raw)) return `请输入有效的整数 (${minimum}-${maximum})`;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    return `请输入有效的整数 (${minimum}-${maximum})`;
+  }
+  return value;
+}
 
 // 配置数据库选项
 export async function configureDatabaseOptions(): Promise<DatabaseConfig> {
@@ -8,31 +34,42 @@ export async function configureDatabaseOptions(): Promise<DatabaseConfig> {
       type: 'select',
       name: 'dialect',
       message: '选择数据库类型:',
-      choices: [
-        { name: 'SQLite (推荐, 零配置)', value: 'sqlite' },
-        { name: 'MySQL', value: 'mysql' },
-        { name: 'PostgreSQL', value: 'pg' },
-        { name: 'MongoDB', value: 'mongodb' },
-        { name: 'Redis', value: 'redis' }
-      ],
+      choices: DATABASE_DIALECT_DEFINITIONS.map((definition) => ({
+        name: databaseChoiceLabel(definition),
+        value: definition.dialect,
+      })),
       default: 'sqlite'
     }
   ]);
 
+  let config: DatabaseConfig;
   switch (dialect) {
     case 'sqlite':
-      return await configureSQLite();
+      config = await configureSQLite();
+      break;
     case 'mysql':
-      return await configureMySQL();
+      config = await configureMySQL();
+      break;
     case 'pg':
-      return await configurePostgreSQL();
+      config = await configurePostgreSQL();
+      break;
     case 'mongodb':
-      return await configureMongoDB();
+      config = await configureMongoDB();
+      break;
     case 'redis':
-      return await configureRedis();
+      config = await configureRedis();
+      break;
+    case 'memory':
+      config = { dialect: 'memory' };
+      break;
     default:
       throw new Error(`未支持的数据库类型: ${dialect}`);
   }
+  const issues = validateDatabaseConfig(config);
+  if (issues.length > 0) {
+    throw new TypeError(`数据库配置不符合 Schema：${issues.map((issue) => issue.message).join('；')}`);
+  }
+  return config;
 }
 
 // SQLite 配置
@@ -42,7 +79,7 @@ async function configureSQLite(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'filename',
       message: 'SQLite 数据库文件路径:',
-      default: './data/bot.db',
+      default: schemaDefault('sqlite', 'filename'),
       validate: (input: string) => {
         if (!input.trim()) return '文件路径不能为空';
         return true;
@@ -57,7 +94,7 @@ async function configureSQLite(): Promise<DatabaseConfig> {
         { name: 'DELETE (默认)', value: 'delete' },
         { name: 'MEMORY (内存数据库)', value: 'memory' }
       ],
-      default: 'wal'
+      default: schemaDefault('sqlite', 'mode')
     }
   ]);
 
@@ -75,26 +112,23 @@ async function configureMySQL(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'host',
       message: 'MySQL 主机地址:',
-      default: 'localhost'
+      default: schemaDefault('mysql', 'host')
     },
     {
       type: 'input',
       name: 'port',
       message: 'MySQL 端口:',
-      default: '3306',
+      default: String(schemaDefault('mysql', 'port')),
       validate: (input: string) => {
-        const port = parseInt(input);
-        if (isNaN(port) || port < 1 || port > 65535) {
-          return '请输入有效的端口号 (1-65535)';
-        }
-        return true;
+        const value = parseIntegerInput(input, 1, 65535);
+        return typeof value === 'number' ? true : value;
       }
     },
     {
       type: 'input',
       name: 'user',
       message: 'MySQL 用户名:',
-      default: 'root'
+      default: schemaDefault('mysql', 'user')
     },
     {
       type: 'password',
@@ -105,7 +139,7 @@ async function configureMySQL(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'database',
       message: 'MySQL 数据库名:',
-      default: 'zhin_bot',
+      default: schemaDefault('mysql', 'database'),
       validate: (input: string) => {
         if (!input.trim()) return '数据库名不能为空';
         return true;
@@ -116,7 +150,7 @@ async function configureMySQL(): Promise<DatabaseConfig> {
   return {
     dialect: 'mysql',
     host: config.host,
-    port: parseInt(config.port),
+    port: Number(config.port),
     user: config.user,
     password: config.password,
     database: config.database
@@ -130,26 +164,23 @@ async function configurePostgreSQL(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'host',
       message: 'PostgreSQL 主机地址:',
-      default: 'localhost'
+      default: schemaDefault('pg', 'host')
     },
     {
       type: 'input',
       name: 'port',
       message: 'PostgreSQL 端口:',
-      default: '5432',
+      default: String(schemaDefault('pg', 'port')),
       validate: (input: string) => {
-        const port = parseInt(input);
-        if (isNaN(port) || port < 1 || port > 65535) {
-          return '请输入有效的端口号 (1-65535)';
-        }
-        return true;
+        const value = parseIntegerInput(input, 1, 65535);
+        return typeof value === 'number' ? true : value;
       }
     },
     {
       type: 'input',
       name: 'user',
       message: 'PostgreSQL 用户名:',
-      default: 'postgres'
+      default: schemaDefault('pg', 'user')
     },
     {
       type: 'password',
@@ -160,7 +191,7 @@ async function configurePostgreSQL(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'database',
       message: 'PostgreSQL 数据库名:',
-      default: 'zhin_bot',
+      default: schemaDefault('pg', 'database'),
       validate: (input: string) => {
         if (!input.trim()) return '数据库名不能为空';
         return true;
@@ -171,7 +202,7 @@ async function configurePostgreSQL(): Promise<DatabaseConfig> {
   return {
     dialect: 'pg',
     host: config.host,
-    port: parseInt(config.port),
+    port: Number(config.port),
     user: config.user,
     password: config.password,
     database: config.database
@@ -185,7 +216,7 @@ async function configureMongoDB(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'url',
       message: 'MongoDB 连接字符串:',
-      default: 'mongodb://localhost:27017',
+      default: schemaDefault('mongodb', 'url'),
       validate: (input: string) => {
         if (!input.trim()) return '连接字符串不能为空';
         if (!input.startsWith('mongodb://') && !input.startsWith('mongodb+srv://')) {
@@ -198,7 +229,7 @@ async function configureMongoDB(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'dbName',
       message: 'MongoDB 数据库名:',
-      default: 'zhin_bot',
+      default: schemaDefault('mongodb', 'dbName'),
       validate: (input: string) => {
         if (!input.trim()) return '数据库名不能为空';
         return true;
@@ -220,19 +251,16 @@ async function configureRedis(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'host',
       message: 'Redis 主机地址:',
-      default: 'localhost'
+      default: schemaDefault('redis', 'socket', 'host')
     },
     {
       type: 'input',
       name: 'port',
       message: 'Redis 端口:',
-      default: '6379',
+      default: String(schemaDefault('redis', 'socket', 'port')),
       validate: (input: string) => {
-        const port = parseInt(input);
-        if (isNaN(port) || port < 1 || port > 65535) {
-          return '请输入有效的端口号 (1-65535)';
-        }
-        return true;
+        const value = parseIntegerInput(input, 1, 65535);
+        return typeof value === 'number' ? true : value;
       }
     },
     {
@@ -244,13 +272,10 @@ async function configureRedis(): Promise<DatabaseConfig> {
       type: 'input',
       name: 'db',
       message: 'Redis 数据库索引:',
-      default: '0',
+      default: String(schemaDefault('redis', 'database')),
       validate: (input: string) => {
-        const db = parseInt(input);
-        if (isNaN(db) || db < 0) {
-          return '请输入有效的数据库索引 (>= 0)';
-        }
-        return true;
+        const value = parseIntegerInput(input, 0);
+        return typeof value === 'number' ? true : '请输入有效的数据库索引 (>= 0)';
       }
     }
   ]);
@@ -259,9 +284,9 @@ async function configureRedis(): Promise<DatabaseConfig> {
     dialect: 'redis',
     socket: {
       host: config.host,
-      port: parseInt(config.port)
+      port: Number(config.port)
     },
     password: config.password || undefined,
-    database: parseInt(config.db)
+    database: Number(config.db)
   };
-}
+}

package/src/env.ts

@@ -104,6 +104,7 @@ export function generateDatabaseEnvVars(config: DatabaseConfig): string {
       );
       break;
     case 'sqlite':
+    case 'memory':
     default:
       // SQLite 不需要额外的环境变量
       break;
@@ -111,3 +112,54 @@ export function generateDatabaseEnvVars(config: DatabaseConfig): string {
 
   return envVars.length > 0 ? `\n\n${envVars.join('\n')}` : '';
 }
+
+/**
+ * Generate a version-control-safe database section for `.env.example`.
+ * User-entered passwords and credential-bearing connection URLs are never
+ * copied from the interactive wizard.
+ */
+export function generateDatabaseEnvExample(config: DatabaseConfig): string {
+  let lines: string[] = [];
+  switch (config.dialect) {
+    case 'mysql':
+      lines = [
+        '# MySQL 数据库配置',
+        'DB_HOST=127.0.0.1',
+        'DB_PORT=3306',
+        'DB_USER=root',
+        'DB_PASSWORD=change-me',
+        'DB_DATABASE=zhin_bot',
+      ];
+      break;
+    case 'pg':
+      lines = [
+        '# PostgreSQL 数据库配置',
+        'DB_HOST=127.0.0.1',
+        'DB_PORT=5432',
+        'DB_USER=postgres',
+        'DB_PASSWORD=change-me',
+        'DB_DATABASE=zhin_bot',
+      ];
+      break;
+    case 'mongodb':
+      lines = [
+        '# MongoDB 数据库配置',
+        'DB_URL=mongodb://127.0.0.1:27017',
+        'DB_NAME=zhin_bot',
+      ];
+      break;
+    case 'redis':
+      lines = [
+        '# Redis 数据库配置',
+        'REDIS_HOST=127.0.0.1',
+        'REDIS_PORT=6379',
+        'REDIS_PASSWORD=',
+        'REDIS_DB=0',
+      ];
+      break;
+    case 'sqlite':
+    case 'memory':
+      return '';
+  }
+  return `\n\n${lines.join('\n')}`;
+}