@southwind-ai/config 0.1.0

package/index.ts

@@ -0,0 +1,4 @@
+export * from "./src/definition.js";
+export * from "./src/environment-loader.js";
+export * from "./src/platform.js";
+export * from "./src/secrets.js";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@southwind-ai/config",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "dependencies": {
+    "@southwind-ai/shared": "workspace:*",
+    "zod": "^4.4.3"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/definition.ts

@@ -0,0 +1,109 @@
+import type { ZodType } from "zod";
+import type { SecretProviderKey } from "./secrets.js";
+
+export type EnvironmentValueDecoder = (value: string) => unknown;
+
+export interface ModuleConfigEnvironmentField {
+  key: string;
+  path: string;
+  defaultValue?: unknown;
+  decode?: EnvironmentValueDecoder;
+  secret?: {
+    provider: SecretProviderKey;
+    required?: boolean;
+  };
+}
+
+export interface ModuleConfigDefinition<T> {
+  key: string;
+  label: string;
+  schema: ZodType<T>;
+  environment: readonly ModuleConfigEnvironmentField[];
+  ownedEnvironmentPrefixes?: readonly string[];
+  ownedEnvironmentKeys?: readonly string[];
+}
+
+export interface ModuleConfigDescriptor {
+  key: string;
+  label: string;
+  fields: Array<{
+    path: string;
+    secret: boolean;
+    required: boolean;
+  }>;
+}
+
+export function defineModuleConfig<T>(
+  definition: ModuleConfigDefinition<T>,
+): ModuleConfigDefinition<T> {
+  validateDefinition(definition);
+  return Object.freeze({
+    ...definition,
+    environment: Object.freeze([...definition.environment]),
+    ownedEnvironmentPrefixes: Object.freeze([
+      ...(definition.ownedEnvironmentPrefixes || []),
+    ]),
+    ownedEnvironmentKeys: Object.freeze([
+      ...(definition.ownedEnvironmentKeys || []),
+    ]),
+  });
+}
+
+export class ModuleConfigRegistry {
+  private readonly definitions = new Map<
+    string,
+    ModuleConfigDefinition<unknown>
+  >();
+
+  register<T>(definition: ModuleConfigDefinition<T>): void {
+    validateDefinition(definition);
+    if (this.definitions.has(definition.key)) {
+      throw new Error(`配置模块重复注册：${definition.key}`);
+    }
+    this.definitions.set(
+      definition.key,
+      definition as ModuleConfigDefinition<unknown>,
+    );
+  }
+
+  get<T>(key: string): ModuleConfigDefinition<T> {
+    const definition = this.definitions.get(key);
+    if (!definition) throw new Error(`未知配置模块：${key}`);
+    return definition as ModuleConfigDefinition<T>;
+  }
+
+  describe(): ModuleConfigDescriptor[] {
+    return [...this.definitions.values()].map((definition) => ({
+      key: definition.key,
+      label: definition.label,
+      fields: definition.environment.map((field) => ({
+        path: field.path,
+        secret: Boolean(field.secret),
+        required: Boolean(field.secret?.required),
+      })),
+    }));
+  }
+}
+
+function validateDefinition<T>(definition: ModuleConfigDefinition<T>): void {
+  if (!/^[a-z][a-z0-9.-]{1,79}$/.test(definition.key)) {
+    throw new Error("配置模块 Key 格式无效");
+  }
+  if (!definition.label.trim()) throw new Error("配置模块名称必填");
+
+  const environmentKeys = new Set<string>();
+  const paths = new Set<string>();
+  for (const field of definition.environment) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(field.key)) {
+      throw new Error(`配置模块 ${definition.key} 包含无效环境变量名`);
+    }
+    if (!/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)*$/.test(field.path)) {
+      throw new Error(`配置模块 ${definition.key} 包含无效字段路径`);
+    }
+    if (environmentKeys.has(field.key) || paths.has(field.path)) {
+      throw new Error(`配置模块 ${definition.key} 包含重复字段`);
+    }
+    environmentKeys.add(field.key);
+    paths.add(field.path);
+  }
+}

package/src/environment-loader.ts

@@ -0,0 +1,240 @@
+import type {
+  ModuleConfigDefinition,
+  ModuleConfigEnvironmentField,
+} from "./definition.js";
+import { SecretRef, type SecretResolver } from "./secrets.js";
+
+export type ConfigEnvironment = Readonly<Record<string, string | undefined>>;
+
+export type ConfigLoadErrorCode =
+  | "CONFIG_UNKNOWN_ENV"
+  | "CONFIG_INVALID_VALUE"
+  | "CONFIG_SECRET_REQUIRED"
+  | "CONFIG_SECRET_UNAVAILABLE"
+  | "CONFIG_ASYNC_SECRET_RESOLVER";
+
+export class ConfigLoadError extends Error {
+  constructor(
+    readonly code: ConfigLoadErrorCode,
+    readonly moduleKey: string,
+    readonly fieldPath?: string,
+  ) {
+    super(errorMessage(code, moduleKey, fieldPath));
+    this.name = "ConfigLoadError";
+  }
+}
+
+export async function loadModuleConfig<T>(
+  definition: ModuleConfigDefinition<T>,
+  environment: ConfigEnvironment,
+  resolver: SecretResolver,
+): Promise<T> {
+  assertKnownEnvironment(definition, environment);
+  const input: Record<string, unknown> = {};
+  for (const field of definition.environment) {
+    const value = await readField(definition.key, field, environment, resolver);
+    if (value !== undefined) setPath(input, field.path, value);
+  }
+  return parseConfig(definition, input);
+}
+
+export function loadModuleConfigSync<T>(
+  definition: ModuleConfigDefinition<T>,
+  environment: ConfigEnvironment,
+  resolver: SecretResolver,
+): T {
+  assertKnownEnvironment(definition, environment);
+  const input: Record<string, unknown> = {};
+  for (const field of definition.environment) {
+    const value = readFieldSync(definition.key, field, environment, resolver);
+    if (value !== undefined) setPath(input, field.path, value);
+  }
+  return parseConfig(definition, input);
+}
+
+export function strictBoolean(value: string): boolean {
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  throw new Error("布尔值只接受 true、false、1 或 0");
+}
+
+export function strictInteger(value: string): number {
+  if (!/^-?\d+$/.test(value.trim())) throw new Error("必须是整数");
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new Error("整数超出安全范围");
+  return parsed;
+}
+
+export function commaSeparated(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function readField(
+  moduleKey: string,
+  field: ModuleConfigEnvironmentField,
+  environment: ConfigEnvironment,
+  resolver: SecretResolver,
+): Promise<unknown> {
+  const raw = environment[field.key];
+  if (!field.secret) return decodeField(moduleKey, field, raw);
+  const ref = createSecretRef(field, raw);
+  if (!ref) return missingSecret(moduleKey, field);
+  try {
+    const value = await resolver.resolve(ref);
+    if (!value?.trim()) return missingSecret(moduleKey, field);
+    return value;
+  } catch {
+    throw new ConfigLoadError(
+      "CONFIG_SECRET_UNAVAILABLE",
+      moduleKey,
+      field.path,
+    );
+  }
+}
+
+function readFieldSync(
+  moduleKey: string,
+  field: ModuleConfigEnvironmentField,
+  environment: ConfigEnvironment,
+  resolver: SecretResolver,
+): unknown {
+  const raw = environment[field.key];
+  if (!field.secret) return decodeField(moduleKey, field, raw);
+  const ref = createSecretRef(field, raw);
+  if (!ref) return missingSecret(moduleKey, field);
+  try {
+    const value = resolver.resolve(ref);
+    if (isPromiseLike(value)) {
+      throw new ConfigLoadError(
+        "CONFIG_ASYNC_SECRET_RESOLVER",
+        moduleKey,
+        field.path,
+      );
+    }
+    if (!value?.trim()) return missingSecret(moduleKey, field);
+    return value;
+  } catch (error) {
+    if (error instanceof ConfigLoadError) throw error;
+    throw new ConfigLoadError(
+      "CONFIG_SECRET_UNAVAILABLE",
+      moduleKey,
+      field.path,
+    );
+  }
+}
+
+function createSecretRef(
+  field: ModuleConfigEnvironmentField,
+  raw: string | undefined,
+): SecretRef | undefined {
+  if (!field.secret) return undefined;
+  if (field.secret.provider === "env") {
+    return raw === undefined || raw === ""
+      ? undefined
+      : new SecretRef("env", field.key);
+  }
+  const locator = raw?.trim();
+  return locator ? new SecretRef("file", locator) : undefined;
+}
+
+function missingSecret(
+  moduleKey: string,
+  field: ModuleConfigEnvironmentField,
+): undefined {
+  if (field.secret?.required) {
+    throw new ConfigLoadError("CONFIG_SECRET_REQUIRED", moduleKey, field.path);
+  }
+  return undefined;
+}
+
+function decodeField(
+  moduleKey: string,
+  field: ModuleConfigEnvironmentField,
+  raw: string | undefined,
+): unknown {
+  if (raw === undefined) return field.defaultValue;
+  try {
+    return field.decode ? field.decode(raw) : raw;
+  } catch {
+    throw new ConfigLoadError("CONFIG_INVALID_VALUE", moduleKey, field.path);
+  }
+}
+
+function parseConfig<T>(
+  definition: ModuleConfigDefinition<T>,
+  input: Record<string, unknown>,
+): T {
+  const result = definition.schema.safeParse(input);
+  if (result.success) return result.data;
+  const firstIssue = result.error.issues[0];
+  throw new ConfigLoadError(
+    "CONFIG_INVALID_VALUE",
+    definition.key,
+    firstIssue?.path.map(String).join(".") || undefined,
+  );
+}
+
+function assertKnownEnvironment<T>(
+  definition: ModuleConfigDefinition<T>,
+  environment: ConfigEnvironment,
+): void {
+  const known = new Set(definition.environment.map((field) => field.key));
+  const exact = new Set(definition.ownedEnvironmentKeys || []);
+  const prefixes = definition.ownedEnvironmentPrefixes || [];
+  const unknown = Object.keys(environment).filter(
+    (key) =>
+      environment[key] !== undefined &&
+      !known.has(key) &&
+      (exact.has(key) || prefixes.some((prefix) => key.startsWith(prefix))),
+  );
+  if (unknown.length > 0) {
+    throw new ConfigLoadError("CONFIG_UNKNOWN_ENV", definition.key);
+  }
+}
+
+function setPath(
+  target: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = path.split(".");
+  let cursor = target;
+  for (const segment of segments.slice(0, -1)) {
+    const existing = cursor[segment];
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+      cursor[segment] = {};
+    }
+    cursor = cursor[segment] as Record<string, unknown>;
+  }
+  const leaf = segments.at(-1);
+  if (leaf) cursor[leaf] = value;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+function errorMessage(
+  code: ConfigLoadErrorCode,
+  moduleKey: string,
+  fieldPath?: string,
+): string {
+  const field = fieldPath ? `，字段 ${fieldPath}` : "";
+  if (code === "CONFIG_UNKNOWN_ENV")
+    return `配置模块 ${moduleKey} 含未知环境变量`;
+  if (code === "CONFIG_SECRET_REQUIRED")
+    return `配置模块 ${moduleKey} 缺少必填 Secret${field}`;
+  if (code === "CONFIG_SECRET_UNAVAILABLE")
+    return `配置模块 ${moduleKey} 无法解析 Secret${field}`;
+  if (code === "CONFIG_ASYNC_SECRET_RESOLVER")
+    return `配置模块 ${moduleKey} 需要异步 SecretResolver${field}`;
+  return `配置模块 ${moduleKey} 的值无效${field}`;
+}

package/src/platform.ts

@@ -0,0 +1,185 @@
+import type { DatabaseDialect } from "@southwind-ai/shared";
+import { z } from "zod";
+import { defineModuleConfig, ModuleConfigRegistry } from "./definition.js";
+import {
+  commaSeparated,
+  loadModuleConfigSync,
+  strictBoolean,
+  strictInteger,
+  type ConfigEnvironment,
+} from "./environment-loader.js";
+import { EnvironmentSecretResolver } from "./secrets.js";
+
+export interface DatabaseConfig {
+  dialect: DatabaseDialect;
+  url?: string;
+  legacyRuoYiMysqlUrl?: string;
+  legacyRuoYiRedisUrl?: string;
+}
+
+export interface PlatformConfig {
+  name: string;
+  logoUrl?: string;
+  enableAI: boolean;
+  database: DatabaseConfig;
+  cache: { redisUrl?: string; healthTimeoutMs: number };
+  security: {
+    sessionCookieName: string;
+    sessionTtlSeconds: number;
+    passwordHash: "argon2id";
+  };
+  license: {
+    enabled: boolean;
+    publicKeyId?: string;
+    publicKey?: string;
+    machineCode?: string;
+  };
+  audit: { enabled: boolean; redactFields: string[] };
+  compatibility: {
+    ruoyiVue: { enabled: boolean; runtimeReadonly: boolean };
+  };
+}
+
+export interface WorkspaceConfig {
+  name: string;
+  description?: string;
+  features: Record<string, boolean>;
+}
+
+export interface ProjectConfig {
+  name: string;
+  modules: string[];
+}
+
+const platformSchema: z.ZodType<PlatformConfig> = z.strictObject({
+  name: z.string().trim().min(1).max(120),
+  logoUrl: z.string().trim().url().optional(),
+  enableAI: z.boolean(),
+  database: z.strictObject({
+    dialect: z.enum(["postgresql", "mysql", "dm", "kingbase"]),
+    url: z.string().trim().min(1).optional(),
+    legacyRuoYiMysqlUrl: z.string().trim().min(1).optional(),
+    legacyRuoYiRedisUrl: z.string().trim().min(1).optional(),
+  }),
+  cache: z.strictObject({
+    redisUrl: z.string().trim().min(1).optional(),
+    healthTimeoutMs: z.number().int().min(50).max(10_000),
+  }),
+  security: z.strictObject({
+    sessionCookieName: z.string().trim().min(1).max(120),
+    sessionTtlSeconds: z.number().int().min(60).max(2_592_000),
+    passwordHash: z.literal("argon2id"),
+  }),
+  license: z.strictObject({
+    enabled: z.boolean(),
+    publicKeyId: z.string().trim().min(1).optional(),
+    publicKey: z.string().trim().min(1).optional(),
+    machineCode: z.string().trim().min(1).optional(),
+  }),
+  audit: z.strictObject({
+    enabled: z.boolean(),
+    redactFields: z.array(z.string().min(1)).min(1),
+  }),
+  compatibility: z.strictObject({
+    ruoyiVue: z.strictObject({
+      enabled: z.boolean(),
+      runtimeReadonly: z.boolean(),
+    }),
+  }),
+});
+
+export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
+  key: "platform.runtime",
+  label: "平台运行配置",
+  schema: platformSchema,
+  ownedEnvironmentPrefixes: [
+    "PLATFORM_",
+    "DATABASE_",
+    "REDIS_",
+    "RUOYI_",
+    "SESSION_",
+    "AUDIT_",
+  ],
+  ownedEnvironmentKeys: [
+    "LICENSE_ENABLED",
+    "LICENSE_PUBLIC_KEY_ID",
+    "LICENSE_PUBLIC_KEY",
+    "LICENSE_MACHINE_CODE",
+  ],
+  environment: [
+    value("PLATFORM_NAME", "name", "Windy Platform"),
+    value("PLATFORM_LOGO_URL", "logoUrl"),
+    value("PLATFORM_ENABLE_AI", "enableAI", false, strictBoolean),
+    value("DATABASE_DIALECT", "database.dialect", "postgresql"),
+    secret("DATABASE_URL", "database.url"),
+    secret("RUOYI_MYSQL_URL", "database.legacyRuoYiMysqlUrl"),
+    secret("RUOYI_REDIS_URL", "database.legacyRuoYiRedisUrl"),
+    secret("REDIS_URL", "cache.redisUrl"),
+    value(
+      "REDIS_HEALTH_TIMEOUT_MS",
+      "cache.healthTimeoutMs",
+      1_500,
+      strictInteger,
+    ),
+    value("SESSION_COOKIE_NAME", "security.sessionCookieName", "windy.sid"),
+    value(
+      "SESSION_TTL_SECONDS",
+      "security.sessionTtlSeconds",
+      28_800,
+      strictInteger,
+    ),
+    value("PLATFORM_PASSWORD_HASH", "security.passwordHash", "argon2id"),
+    value("LICENSE_ENABLED", "license.enabled", true, strictBoolean),
+    value("LICENSE_PUBLIC_KEY_ID", "license.publicKeyId"),
+    value("LICENSE_PUBLIC_KEY", "license.publicKey"),
+    secret("LICENSE_MACHINE_CODE", "license.machineCode"),
+    value("AUDIT_ENABLED", "audit.enabled", true, strictBoolean),
+    value(
+      "AUDIT_REDACT_FIELDS",
+      "audit.redactFields",
+      ["password", "token", "secret"],
+      commaSeparated,
+    ),
+    value(
+      "RUOYI_COMPAT_ENABLED",
+      "compatibility.ruoyiVue.enabled",
+      false,
+      strictBoolean,
+    ),
+    value(
+      "RUOYI_RUNTIME_READONLY",
+      "compatibility.ruoyiVue.runtimeReadonly",
+      true,
+      strictBoolean,
+    ),
+  ],
+});
+
+export function createPlatformConfigRegistry(): ModuleConfigRegistry {
+  const registry = new ModuleConfigRegistry();
+  registry.register(platformConfigDefinition);
+  return registry;
+}
+
+export function loadPlatformConfig(
+  environment: ConfigEnvironment = process.env,
+): PlatformConfig {
+  return loadModuleConfigSync(
+    platformConfigDefinition,
+    environment,
+    new EnvironmentSecretResolver(environment),
+  );
+}
+
+function value(
+  key: string,
+  path: string,
+  defaultValue?: unknown,
+  decode?: (value: string) => unknown,
+) {
+  return { key, path, defaultValue, decode };
+}
+
+function secret(key: string, path: string) {
+  return { key, path, secret: { provider: "env" as const } };
+}

package/src/secrets.ts

@@ -0,0 +1,69 @@
+export type SecretProviderKey = "env" | "file";
+
+export class SecretRef {
+  readonly #provider: SecretProviderKey;
+  readonly #locator: string;
+
+  constructor(provider: SecretProviderKey, locator: string) {
+    this.#provider = provider;
+    this.#locator = locator;
+    Object.freeze(this);
+  }
+
+  locatorFor(provider: SecretProviderKey): string {
+    if (provider !== this.#provider) {
+      throw new Error("SecretResolver 与 SecretRef Provider 不匹配");
+    }
+    return this.#locator;
+  }
+
+  toJSON(): undefined {
+    return undefined;
+  }
+
+  toString(): string {
+    return "[SecretRef]";
+  }
+}
+
+export interface SecretResolver {
+  resolve(ref: SecretRef): string | undefined | Promise<string | undefined>;
+}
+
+export class EnvironmentSecretResolver implements SecretResolver {
+  constructor(
+    private readonly environment: Readonly<Record<string, string | undefined>>,
+  ) {}
+
+  resolve(ref: SecretRef): string | undefined {
+    return this.environment[ref.locatorFor("env")];
+  }
+}
+
+export class CompositeSecretResolver implements SecretResolver {
+  constructor(
+    private readonly resolvers: Readonly<
+      Partial<Record<SecretProviderKey, SecretResolver>>
+    >,
+  ) {}
+
+  resolve(ref: SecretRef): string | undefined | Promise<string | undefined> {
+    for (const provider of ["env", "file"] as const) {
+      try {
+        ref.locatorFor(provider);
+        const resolver = this.resolvers[provider];
+        if (!resolver) throw new Error("Secret Provider 未配置");
+        return resolver.resolve(ref);
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          error.message === "SecretResolver 与 SecretRef Provider 不匹配"
+        ) {
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error("未知 Secret Provider");
+  }
+}