@zhin.js/scaffold-wizard 1.1.0 → 1.1.2

package/src/index.ts

@@ -1,5 +1,17 @@
 export type { InitOptions, DatabaseConfig } from './types.js';
-export { DATABASE_PACKAGES } from './types.js';
+export { DATABASE_DRIVER_VERSIONS, DATABASE_PACKAGES } from './types.js';
+export {
+  DATABASE_DIALECT_DEFINITIONS,
+  databaseChoiceLabel,
+  getDatabaseDialectDefinition,
+  validateDatabaseConfig,
+} from './database-definitions.js';
+export type {
+  DatabaseDialect,
+  DatabaseDialectDefinition,
+  DatabaseDriverDefinition,
+  DatabaseSchemaIssue,
+} from './database-definitions.js';
 
 export type { AdapterSetupResult, AdapterPluginInstance, AdapterDefinition } from './adapter.js';
 export {
@@ -27,7 +39,6 @@ export {
   generateAIEnvVars,
   generateAIConfigYaml,
   generateAIConfigJSON,
-  generateAIConfigToml,
   RECOMMENDED_AI_DEFAULTS,
 } from './ai.js';
 
@@ -36,6 +47,7 @@ export { configureDatabaseOptions } from './database.js';
 export {
   formatEnvValue,
   mergeEnvText,
+  generateDatabaseEnvExample,
   generateDatabaseEnvVars,
 } from './env.js';
 
@@ -46,7 +58,7 @@ export {
   listAIDependencyNames,
   formatAIDependencyHint,
   isAiEnabledInConfig,
-  resolveDefaultProviderFromConfig,
+  resolveAgentProviderFromConfig,
   getRequiredAIDependenciesForConfig,
   diagnoseAIDependencies,
   formatAIDependencyFixCommand,
@@ -61,9 +73,9 @@ export type { AiStackIncompatibility } from './project-deps.js';
 export {
   ZHIN_STACK_VERSIONS,
   DEFAULT_CREATE_BOT_HTTP_PORT,
-  CREATE_BOT_NPMRC,
+  CREATE_BOT_PACKAGE_MANAGER,
   getCreateBotBaseDependencies,
-  getCreateBotPnpmConfig,
+  getCreateBotPnpmWorkspaceConfig,
   getRequiredZhinDependenciesForConfig,
   diagnoseZhinStackDependencies,
   formatZhinStackFixCommand,
@@ -119,7 +131,7 @@ export {
   mergePluginManifestIntoPackageJson,
   finalizeWizardOptions,
   applyWizardOptionsToConfig,
-  normalizePluginsMap,
+  clonePluginConfigurationMap,
   materializeDatabaseConfig,
   buildRuntimeConfigDocument,
   serializeRuntimeConfig,

package/src/optional-peers.ts

@@ -1,5 +1,6 @@
 import fs from 'fs-extra';
 import path from 'node:path';
+import { readPluginConfigurationMap } from '@zhin.js/plugin-runtime';
 import { findMissingPackageDependencies, findUnresolvedPackageInstalls, type PackageJsonLike } from './project-deps.js';
 
 export const SPEECH_PACKAGE = '@zhin.js/speech';
@@ -38,21 +39,10 @@ function readSpeechStrategy(config: Record<string, unknown>): string | undefined
 }
 
 function configUsesHtmlImageAdapter(config: Record<string, unknown>): boolean {
-  const plugins = Array.isArray(config.plugins)
-    ? config.plugins.filter((p): p is string => typeof p === 'string')
-    : [];
-  for (const plugin of plugins) {
+  for (const instanceKey of Object.keys(readPluginConfigurationMap(config))) {
+    if (ADAPTERS_PREFER_HTML_IMAGE.has(instanceKey)) return true;
     for (const ctx of ADAPTERS_PREFER_HTML_IMAGE) {
-      if (plugin.includes(`adapter-${ctx}`)) return true;
-    }
-  }
-  // 新 runtime 配置形态：plugins 为 instanceKey → 配置 的映射，instanceKey 即适配器 context
-  if (config.plugins && typeof config.plugins === 'object' && !Array.isArray(config.plugins)) {
-    for (const instanceKey of Object.keys(config.plugins as Record<string, unknown>)) {
-      if (ADAPTERS_PREFER_HTML_IMAGE.has(instanceKey)) return true;
-      for (const ctx of ADAPTERS_PREFER_HTML_IMAGE) {
-        if (instanceKey.includes(`adapter-${ctx}`)) return true;
-      }
+      if (instanceKey.includes(`adapter-${ctx}`)) return true;
     }
   }
   const endpoints = Array.isArray(config.endpoints) ? config.endpoints : [];

package/src/project-config-plan.ts

@@ -1,17 +1,16 @@
 import fs from 'fs-extra';
 import path from 'node:path';
 import yaml from 'yaml';
-import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import {
+  readPluginConfigurationMap,
+  ROOT_CONFIG_FILE_NAMES,
+  rootConfigFormat,
+  selectRootConfigFile,
+  type RootConfigFormat,
+} from '@zhin.js/plugin-runtime';
 import { providerSdkFor } from './ai.js';
 
 const CONSOLE_URL = 'https://console.zhin.dev';
-const CONFIG_CANDIDATES = [
-  'zhin.config.yml',
-  'zhin.config.yaml',
-  'zhin.config.json',
-  'zhin.config.toml',
-  'zhin.config.ts',
-] as const;
 const SANDBOX_PLUGIN = '@zhin.js/adapter-sandbox';
 const LEGACY_AI_PROVIDER_FIELDS = ['driver', 'api', 'preset', 'spec'] as const;
 
@@ -23,7 +22,7 @@ export function packageToInstanceKey(packageName: string): string {
   return name.replace(/^(adapter|plugin|service)-/, '');
 }
 
-export type ProjectConfigFormat = 'yaml' | 'json' | 'toml' | 'ts';
+export type ProjectConfigFormat = RootConfigFormat;
 
 export interface LoadedProjectConfig {
   status: 'loaded' | 'missing' | 'unsupported';
@@ -70,12 +69,7 @@ export interface ConsoleConfigDiagnosis {
 }
 
 function configFormatFromPath(filePath: string): ProjectConfigFormat | null {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.yml' || ext === '.yaml') return 'yaml';
-  if (ext === '.json') return 'json';
-  if (ext === '.toml') return 'toml';
-  if (ext === '.ts') return 'ts';
-  return null;
+  return rootConfigFormat(filePath) ?? null;
 }
 
 function cloneConfig(config: Record<string, unknown>): Record<string, unknown> {
@@ -83,39 +77,28 @@ function cloneConfig(config: Record<string, unknown>): Record<string, unknown> {
 }
 
 function parseConfig(content: string, format: ProjectConfigFormat): Record<string, unknown> {
-  if (format === 'yaml') {
-    const parsed = yaml.parse(content) as unknown;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed as Record<string, unknown>
-      : {};
-  }
   if (format === 'json') {
     const parsed = JSON.parse(content) as unknown;
     return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
       ? parsed as Record<string, unknown>
       : {};
   }
-  if (format === 'toml') {
-    const parsed = parseToml(content) as unknown;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? parsed as Record<string, unknown>
-      : {};
-  }
-  return {};
+  const parsed = yaml.parse(content) as unknown;
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+    ? parsed as Record<string, unknown>
+    : {};
 }
 
 function serializeConfig(config: Record<string, unknown>, format: ProjectConfigFormat): string {
   if (format === 'json') return `${JSON.stringify(config, null, 2)}\n`;
-  if (format === 'toml') return stringifyToml(config as Record<string, unknown>);
   return yaml.stringify(config);
 }
 
 function findProjectConfigPath(cwd: string): string | null {
-  for (const candidate of CONFIG_CANDIDATES) {
-    const configPath = path.join(cwd, candidate);
-    if (fs.existsSync(configPath)) return configPath;
-  }
-  return null;
+  const existing = ROOT_CONFIG_FILE_NAMES
+    .map((candidate) => path.join(cwd, candidate))
+    .filter((configPath) => fs.existsSync(configPath));
+  return selectRootConfigFile(existing) ?? null;
 }
 
 export function loadProjectConfig(cwd = process.cwd(), configPath?: string): LoadedProjectConfig {
@@ -126,7 +109,7 @@ export function loadProjectConfig(cwd = process.cwd(), configPath?: string): Loa
       cwd,
       config: {},
       writable: false,
-      message: '未找到 zhin.config.yml/json/toml',
+      message: '未找到 Root YAML/JSON 配置文件',
     };
   }
 
@@ -144,51 +127,35 @@ export function loadProjectConfig(cwd = process.cwd(), configPath?: string): Loa
     };
   }
 
-  if (format === 'ts') {
+  const content = fs.readFileSync(resolvedPath, 'utf8');
+  const config = parseConfig(content, format);
+  try {
+    readPluginConfigurationMap(config, relativePath);
+  } catch (error) {
     return {
       status: 'unsupported',
       cwd,
       configPath: resolvedPath,
       relativePath,
       format,
-      config: {},
+      config,
       writable: false,
-      message: 'zhin.config.ts 只读；请迁移为 zhin.config.yml/json/toml 后自动修复',
+      message: `${error instanceof Error ? error.message : String(error)}；请先运行 zhin migrate`,
     };
   }
-
-  const content = fs.readFileSync(resolvedPath, 'utf8');
   return {
     status: 'loaded',
     cwd,
     configPath: resolvedPath,
     relativePath,
     format,
-    config: parseConfig(content, format),
+    config,
     writable: true,
   };
 }
 
 function ensurePlugins(config: Record<string, unknown>, pluginsToAdd: readonly string[], mutations: string[]): void {
-  if (Array.isArray(config.plugins)) {
-    // legacy 数组形式：保持原形态追加，避免改写旧项目结构
-    const plugins = config.plugins.filter((p): p is string => typeof p === 'string');
-    let changed = false;
-    for (const plugin of pluginsToAdd) {
-      if (plugins.includes(plugin)) continue;
-      plugins.push(plugin);
-      mutations.push(`added ${plugin} to plugins`);
-      changed = true;
-    }
-    if (changed) {
-      config.plugins = plugins;
-    }
-    return;
-  }
-  // 新 Plugin Runtime：plugins 为 <instanceKey>: <配置> 映射
-  const plugins = config.plugins && typeof config.plugins === 'object'
-    ? { ...(config.plugins as Record<string, unknown>) }
-    : {};
+  const plugins = { ...readPluginConfigurationMap(config) };
   let changed = false;
   for (const pkg of pluginsToAdd) {
     const instanceKey = packageToInstanceKey(pkg);
@@ -197,7 +164,7 @@ function ensurePlugins(config: Record<string, unknown>, pluginsToAdd: readonly s
     mutations.push(`added ${instanceKey} (${pkg}) to plugins`);
     changed = true;
   }
-  if (changed || !config.plugins || typeof config.plugins !== 'object') {
+  if (changed || config.plugins === undefined) {
     config.plugins = plugins;
   }
 }
@@ -321,6 +288,8 @@ function applyAiLegacyMigration(config: Record<string, unknown>, mutations: stri
 
 export function createProjectConfigPlan(options: ProjectConfigPlanOptions): ProjectConfigPlan {
   const cwd = options.cwd ?? options.loaded?.cwd ?? process.cwd();
+  const configuredFormat = options.format
+    ?? (options.configPath ? configFormatFromPath(options.configPath) ?? undefined : undefined);
   const loaded = options.loaded ?? (
     options.config
       ? {
@@ -328,9 +297,9 @@ export function createProjectConfigPlan(options: ProjectConfigPlanOptions): Proj
         cwd,
         configPath: options.configPath,
         relativePath: options.configPath ? path.relative(cwd, options.configPath) : undefined,
-        format: options.format ?? (options.configPath ? configFormatFromPath(options.configPath) ?? undefined : undefined),
+        format: configuredFormat,
         config: options.config,
-        writable: Boolean(options.configPath && (options.format ?? configFormatFromPath(options.configPath)) !== 'ts'),
+        writable: Boolean(options.configPath && configuredFormat),
       }
       : loadProjectConfig(cwd, options.configPath)
   );
@@ -373,7 +342,7 @@ export function createProjectConfigPlan(options: ProjectConfigPlanOptions): Proj
 
 export function renderProjectConfigPatch(plan: ProjectConfigPlan): string {
   if (!plan.changed) return '配置无需改动。';
-  const format = plan.format && plan.format !== 'ts' ? plan.format : 'yaml';
+  const format = plan.format ?? 'yaml';
   const name = plan.relativePath ?? 'zhin.config.yml';
   return [
     `# ${name}`,
@@ -384,7 +353,7 @@ export function renderProjectConfigPatch(plan: ProjectConfigPlan): string {
 
 export async function applyProjectConfigPlan(plan: ProjectConfigPlan): Promise<boolean> {
   if (!plan.changed) return false;
-  if (!plan.writable || !plan.configPath || !plan.format || plan.format === 'ts') return false;
+  if (!plan.writable || !plan.configPath || !plan.format) return false;
   await fs.writeFile(plan.configPath, serializeConfig(plan.after, plan.format));
   return true;
 }
@@ -395,20 +364,7 @@ export function diagnoseConsoleConfig(config: Record<string, unknown>): ConsoleC
     : {};
   const corsOrigins = Array.isArray(http.corsOrigins) ? http.corsOrigins : [];
 
-  if (Array.isArray(config.plugins)) {
-    // legacy 数组形式配置
-    const plugins = config.plugins.filter((p): p is string => typeof p === 'string');
-    return {
-      missingSandboxPlugin: !plugins.includes(SANDBOX_PLUGIN),
-      missingConsoleOrigin: !hasConsoleOrigin(corsOrigins.filter((origin): origin is string => typeof origin === 'string')),
-      missingHttpToken: typeof http.token !== 'string' || http.token.trim().length === 0,
-    };
-  }
-
-  // 新 Plugin Runtime：Console Host 由 CLI 装配，无需 host 插件；Sandbox 为 plugins.sandbox 实例
-  const plugins = config.plugins && typeof config.plugins === 'object'
-    ? config.plugins as Record<string, unknown>
-    : {};
+  const plugins = readPluginConfigurationMap(config);
   return {
     missingSandboxPlugin: !('sandbox' in plugins),
     missingConsoleOrigin: !hasConsoleOrigin(corsOrigins.filter((origin): origin is string => typeof origin === 'string')),

package/src/project-deps.ts

@@ -88,7 +88,7 @@ function packagesForSdkIds(sdkIds: Iterable<string>): Record<string, string> {
 
 function collectSdkPackagesFromSetup(ai: AISetupConfig): Record<string, string> {
   const sdkIds = new Set<string>();
-  const agentProvider = ai.agentProvider ?? ai.defaultProvider;
+  const agentProvider = ai.agentProvider;
   if (agentProvider) {
     const id = inferSdkId(agentProvider, ai.providers?.[agentProvider] as { sdk?: string });
     if (id) sdkIds.add(id);
@@ -124,7 +124,7 @@ function collectSdkPackagesFromConfig(config: { ai?: unknown }): Record<string,
   }
 
   if (sdkIds.size === 0) {
-    const alias = resolveDefaultProviderFromConfig(config);
+    const alias = resolveAgentProviderFromConfig(config);
     if (alias) {
       const id = inferSdkId(alias, providers?.[alias]);
       if (id) sdkIds.add(id);
@@ -249,7 +249,7 @@ export function isAiEnabledInConfig(config: { ai?: unknown }): boolean {
   return false;
 }
 
-export function resolveDefaultProviderFromConfig(config: { ai?: unknown }): string | undefined {
+export function resolveAgentProviderFromConfig(config: { ai?: unknown }): string | undefined {
   const ai = config.ai;
   if (!ai || typeof ai !== 'object' || Array.isArray(ai)) return undefined;
   const rec = ai as Record<string, unknown>;
@@ -265,7 +265,6 @@ export function resolveDefaultProviderFromConfig(config: { ai?: unknown }): stri
     const first = Object.keys(providers as Record<string, unknown>)[0];
     if (first) return first;
   }
-  if (rec.defaultProvider != null) return String(rec.defaultProvider);
   return undefined;
 }
 
@@ -281,7 +280,7 @@ export function getRequiredAIDependenciesForConfig(config: { ai?: unknown }): Re
   const ai = config.ai as Record<string, unknown>;
   const setup: AISetupConfig = {
     enabled: true,
-    agentProvider: resolveDefaultProviderFromConfig(config),
+    agentProvider: resolveAgentProviderFromConfig(config),
     providers: ai.providers as AISetupConfig['providers'],
     memoryMcp: aiConfigNeedsMcp(ai),
   };
@@ -365,7 +364,7 @@ export function diagnoseAIDependencies(
   const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
   return {
     enabled: true,
-    provider: resolveDefaultProviderFromConfig(config),
+    provider: resolveAgentProviderFromConfig(config),
     required,
     missingFromPackageJson,
     outdatedInPackageJson,

package/src/types.ts

@@ -1,5 +1,6 @@
 import type { AISetupConfig } from './ai.js';
 import type { AdapterSetupResult } from './adapter.js';
+import { DATABASE_DIALECT_DEFINITIONS } from './database-definitions.js';
 
 export type { AISetupConfig } from './ai.js';
 export type { AdapterSetupResult } from './adapter.js';
@@ -7,7 +8,7 @@ export type { AdapterSetupResult } from './adapter.js';
 export interface InitOptions {
   name?: string;
   template?: 'default' | 'life-assistant';
-  config?: 'json' | 'yaml' | 'toml';
+  config?: 'json' | 'yaml';
   runtime?: 'node' | 'bun';
   yes?: boolean;
   httpToken?: string;
@@ -19,15 +20,17 @@ export interface InitOptions {
 }
 
 export interface DatabaseConfig {
-  dialect: 'sqlite' | 'mysql' | 'pg' | 'mongodb' | 'redis';
+  dialect: 'sqlite' | 'mysql' | 'pg' | 'mongodb' | 'redis' | 'memory';
   [key: string]: any;
 }
 
-// 数据库配置映射（SQLite 使用 Node 内置 node:sqlite，无需额外安装）
-export const DATABASE_PACKAGES: Record<DatabaseConfig['dialect'], string | undefined> = {
-  sqlite: undefined,
-  mysql: 'mysql2',
-  pg: 'pg',
-  mongodb: 'mongodb',
-  redis: 'redis'
-};
+// 数据库驱动映射（SQLite / Memory 使用内置实现，无需额外安装）
+export const DATABASE_PACKAGES = Object.freeze(Object.fromEntries(
+  DATABASE_DIALECT_DEFINITIONS.map((definition) => [definition.dialect, definition.driver?.package]),
+)) as Readonly<Record<DatabaseConfig['dialect'], string | undefined>>;
+
+export const DATABASE_DRIVER_VERSIONS = Object.freeze(Object.fromEntries(
+  DATABASE_DIALECT_DEFINITIONS.flatMap((definition) => definition.driver
+    ? [[definition.driver.package, definition.driver.version] as const]
+    : []),
+)) as Readonly<Record<string, string>>;

package/src/zhin-stack-deps.ts

@@ -1,12 +1,13 @@
 import { createRequire } from 'node:module';
 import fs from 'fs-extra';
 import path from 'node:path';
-import { DATABASE_PACKAGES } from './types.js';
+import { DATABASE_DRIVER_VERSIONS, DATABASE_PACKAGES } from './types.js';
 import { findMissingPackageDependencies, findUnresolvedPackageInstalls, isAiEnabledInConfig, type PackageJsonLike } from './project-deps.js';
 
 /**
- * User project dependency policy: scaffolded dependencies intentionally float to latest.
- * WARNING: this is not reproducible; pin versions for production. See scaffold-wizard README.
+ * User project dependency policy: scaffolded Zhin packages intentionally float to latest.
+ * Database drivers use the live-tested ranges declared by the database definitions.
+ * WARNING: `latest` is not reproducible; pin Zhin package versions for production.
  */
 export const ZHIN_STACK_VERSIONS = {
   'zhin.js': 'latest',
@@ -23,6 +24,7 @@ export const ZHIN_STACK_VERSIONS = {
   '@zhin.js/layout': 'latest',
   '@zhin.js/page': 'latest',
   '@zhin.js/prompt-section': 'latest',
+  '@zhin.js/skill': 'latest',
   '@zhin.js/tool': 'latest',
   '@zhin.js/client': 'latest',
   '@zhin.js/contract': 'latest',
@@ -110,30 +112,20 @@ function resolveStackVersion(packageName: string): string {
   return ZHIN_STACK_VERSIONS[packageName as ZhinStackPackage] ?? 'latest';
 }
 
-function collectZhinPluginsFromConfig(config: Record<string, unknown>): string[] {
-  // legacy 数组形式：条目即包名
-  if (Array.isArray(config.plugins)) {
-    const plugins = config.plugins.filter((p): p is string => typeof p === 'string');
-    return [...new Set(plugins.filter((p) => p.startsWith('@zhin.js/')))];
-  }
-  // 新 runtime：plugins 为 instanceKey 映射，包名在 package.json zhin.plugins 清单中，
-  // 无法从配置推导；仅收集直接以包名出现的键（防御性）
-  if (config.plugins && typeof config.plugins === 'object') {
-    return Object.keys(config.plugins as Record<string, unknown>).filter((key) => key.startsWith('@zhin.js/'));
-  }
-  return [];
-}
-
 /** create-zhin / minimal-bot 默认 Host 端口（避免与常见 8086 占用冲突） */
 export const DEFAULT_CREATE_BOT_HTTP_PORT = 8068;
 
-/** create-zhin 生成项目的 .npmrc（避免全局 strict-peer-dependencies 阻断 AI 栈安装） */
-export const CREATE_BOT_NPMRC = 'strict-peer-dependencies=false\n';
+/** create-zhin 生成项目固定使用的 pnpm 版本。 */
+export const CREATE_BOT_PACKAGE_MANAGER = 'pnpm@11.27.1';
 
-/** create-zhin 生成项目的 pnpm 配置 */
-export function getCreateBotPnpmConfig(_aiEnabled?: boolean): Record<string, unknown> {
+/** create-zhin 生成项目的 pnpm-workspace.yaml 配置。 */
+export function getCreateBotPnpmWorkspaceConfig(): Record<string, unknown> {
   return {
-    onlyBuiltDependencies: ['esbuild'],
+    packages: ['.', 'plugins/*', 'packages/*'],
+    strictPeerDependencies: false,
+    allowBuilds: {
+      esbuild: true,
+    },
   };
 }
 
@@ -144,6 +136,7 @@ export function getCreateBotPnpmConfig(_aiEnabled?: boolean): Record<string, unk
 export function getCreateBotBaseDependencies(): Record<string, string> {
   return {
     'zhin.js': ZHIN_STACK_VERSIONS['zhin.js'],
+    '@zhin.js/skill': ZHIN_STACK_VERSIONS['@zhin.js/skill'],
   };
 }
 
@@ -153,17 +146,13 @@ export function getRequiredZhinDependenciesForConfig(config: Record<string, unkn
     'zhin.js': ZHIN_STACK_VERSIONS['zhin.js'],
   };
 
-  for (const plugin of collectZhinPluginsFromConfig(config)) {
-    deps[plugin] = resolveStackVersion(plugin);
-  }
-
   const database = config.database;
   if (database && typeof database === 'object' && !Array.isArray(database)) {
     deps['@zhin.js/database'] = ZHIN_STACK_VERSIONS['@zhin.js/database'];
     const dialect = String((database as Record<string, unknown>).dialect ?? '');
     const driver = DATABASE_PACKAGES[dialect as keyof typeof DATABASE_PACKAGES];
     if (driver) {
-      deps[driver] = 'latest';
+      deps[driver] = DATABASE_DRIVER_VERSIONS[driver];
     }
   }