@southwind-ai/modules 0.1.0

package/index.ts

@@ -0,0 +1,8 @@
+export * from "./src/manifest.js";
+export * from "./src/composition.js";
+export * from "./src/catalog-validation.js";
+export * from "./src/menu-composition.js";
+export * from "./src/registry.js";
+export * from "./src/system-modules.js";
+export * from "./src/system-module-catalog.js";
+export * from "./src/system-api-permissions.js";

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@southwind-ai/modules",
+  "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:*"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/catalog-validation.ts

@@ -0,0 +1,123 @@
+import {
+  AUDIT_ACTION_DEFINITIONS,
+  isAuditActionDefinition,
+  LICENSE_CATALOG,
+  type AuditActionDefinition,
+  type FeatureFlagDefinition,
+  type LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+export interface PlatformCapabilityCatalogs {
+  auditActions: readonly AuditActionDefinition[];
+  licenseVersions: readonly LicenseCatalogDefinition[];
+}
+
+export function validateCapabilityCatalogs(
+  modules: readonly ModuleManifest[],
+): PlatformCapabilityCatalogs {
+  const auditActions = composeAuditActionCatalog(modules);
+  validateFeatureCatalog(modules, LICENSE_CATALOG);
+  return {
+    auditActions,
+    licenseVersions: LICENSE_CATALOG,
+  };
+}
+
+export function composeAuditActionCatalog(
+  modules: readonly ModuleManifest[],
+): AuditActionDefinition[] {
+  const definitions = new Map<string, AuditActionDefinition>(
+    AUDIT_ACTION_DEFINITIONS.map((definition) => [
+      definition.key,
+      { ...definition },
+    ]),
+  );
+  const registrations = modules.flatMap((module) => module.auditActions);
+
+  for (const registration of registrations) {
+    if (!isAuditActionDefinition(registration)) continue;
+    validateAuditDefinition(registration);
+    if (definitions.has(registration.key)) {
+      throw new Error(`审计动作定义重复：${registration.key}`);
+    }
+    definitions.set(registration.key, { ...registration });
+  }
+
+  for (const registration of registrations) {
+    const key =
+      typeof registration === "string" ? registration : registration.key;
+    if (!definitions.has(key)) {
+      throw new Error(`引用了未定义审计动作：${key}`);
+    }
+  }
+
+  return [...definitions.values()].sort((left, right) =>
+    left.key.localeCompare(right.key),
+  );
+}
+
+export function validateFeatureCatalog(
+  modules: readonly ModuleManifest[],
+  licenseCatalog: readonly LicenseCatalogDefinition[],
+): void {
+  const features = modules.flatMap((module) => module.features);
+  const byKey = new Map(features.map((feature) => [feature.key, feature]));
+  const licenseKeys = new Set(licenseCatalog.map(({ key }) => key));
+
+  for (const feature of features) {
+    for (const dependency of feature.dependencies || []) {
+      if (dependency === feature.key) {
+        throw new Error(`Feature ${feature.key} 不能依赖自身`);
+      }
+      if (!byKey.has(dependency)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未注册依赖：${dependency}`,
+        );
+      }
+    }
+    for (const version of feature.allowedLicenseVersions || []) {
+      if (!licenseKeys.has(version)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未知 License 版本：${version}`,
+        );
+      }
+    }
+  }
+
+  validateFeatureCycles(features, byKey);
+}
+
+function validateAuditDefinition(definition: AuditActionDefinition): void {
+  if (
+    !definition.key.trim() ||
+    !definition.label.trim() ||
+    !definition.description.trim()
+  ) {
+    throw new Error("审计动作 Key、名称和说明不能为空");
+  }
+}
+
+function validateFeatureCycles(
+  features: readonly FeatureFlagDefinition[],
+  byKey: ReadonlyMap<string, FeatureFlagDefinition>,
+): void {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  const visit = (feature: FeatureFlagDefinition): void => {
+    if (visited.has(feature.key)) return;
+    if (visiting.has(feature.key)) {
+      throw new Error(`Feature 依赖存在循环：${feature.key}`);
+    }
+    visiting.add(feature.key);
+    for (const dependency of feature.dependencies || []) {
+      const target = byKey.get(dependency);
+      if (target) visit(target);
+    }
+    visiting.delete(feature.key);
+    visited.add(feature.key);
+  };
+
+  for (const feature of features) visit(feature);
+}

package/src/composition.ts

@@ -0,0 +1,344 @@
+import type { MenuNode } from "@southwind-ai/shared";
+import type {
+  ModuleImplementationBindings,
+  ModuleManifest,
+} from "./manifest.js";
+import { composeModuleMenus } from "./menu-composition.js";
+import { validateCapabilityCatalogs } from "./catalog-validation.js";
+
+export interface ValidatedModuleComposition {
+  modules: readonly ModuleManifest[];
+  moduleOrder: readonly string[];
+}
+
+export function apiRouteKey(input: { method: string; path: string }): string {
+  return `${input.method.toUpperCase()} ${input.path}`;
+}
+
+export function validateModuleComposition(
+  modules: readonly ModuleManifest[],
+  implementations: ModuleImplementationBindings = {},
+): ValidatedModuleComposition {
+  const moduleNames = unique(
+    "模块",
+    modules.map(({ name }) => name),
+  );
+  const moduleOrder = validateDependencies(modules, moduleNames);
+  const permissions = unique(
+    "权限",
+    modules.flatMap((module) => module.permissions.map(({ key }) => key)),
+  );
+  const features = unique(
+    "Feature",
+    modules.flatMap((module) => module.features.map(({ key }) => key)),
+  );
+  const catalogs = validateCapabilityCatalogs(modules);
+  const audits = new Set(catalogs.auditActions.map(({ key }) => key));
+  const menus = composeModuleMenus(modules).flatMap((menu) =>
+    flattenMenus([menu]),
+  );
+  unique(
+    "菜单",
+    menus.map(({ key }) => key),
+  );
+  const adminRoutes = modules.flatMap((module) => module.adminRoutes);
+  unique(
+    "Admin Route",
+    adminRoutes.map(({ key }) => key),
+  );
+  unique(
+    "Admin Route 路径",
+    adminRoutes.map(({ path }) => path),
+  );
+  const apiRoutes = modules.flatMap((module) => module.apiPermissions);
+  unique("API Route", apiRoutes.map(apiRouteKey));
+  const tasks = modules.flatMap((module) => module.tasks);
+  unique(
+    "定时任务",
+    tasks.map(({ key }) => key),
+  );
+  const tools = modules.flatMap((module) => module.tools);
+  unique(
+    "Agent Tool",
+    tools.map(({ key }) => key),
+  );
+  const providers = modules.flatMap((module) => module.providers);
+  unique(
+    "Provider",
+    providers.map(({ key }) => key),
+  );
+  const dataPolicies = modules.flatMap((module) => module.dataPolicies || []);
+  unique(
+    "数据治理策略",
+    dataPolicies.map(({ key }) => key),
+  );
+  unique(
+    "数据治理资源",
+    dataPolicies.map(({ resourceType }) => resourceType),
+  );
+  const schemas = modules.flatMap((module) => module.schemaExports);
+  unique(
+    "Schema Export",
+    schemas.map(({ key }) => key),
+  );
+  unique(
+    "Migration",
+    modules.flatMap((module) => module.migrations.map(({ id }) => id)),
+  );
+
+  for (const module of modules) {
+    validateReferences(module, permissions, features, audits);
+    validateDataPolicies(module, modules);
+  }
+  validateMenuRoutes(menus, adminRoutes);
+  validateSchemaMigrations(schemas);
+  validateImplementations(
+    "Admin Route",
+    adminRoutes.map(({ key }) => key),
+    implementations.adminRoutes,
+  );
+  validateImplementations(
+    "API Route",
+    apiRoutes.map(apiRouteKey),
+    implementations.apiRoutes,
+  );
+  validateImplementations(
+    "定时任务",
+    tasks.map(({ key }) => key),
+    implementations.tasks,
+  );
+  validateImplementations(
+    "Agent Tool",
+    tools.map(({ key }) => key),
+    implementations.tools,
+  );
+  validateImplementations(
+    "Provider",
+    providers.map(({ key }) => key),
+    implementations.providers,
+  );
+
+  return { modules, moduleOrder };
+}
+
+function validateDataPolicies(
+  module: ModuleManifest,
+  modules: readonly ModuleManifest[],
+): void {
+  const permissionByKey = new Map(
+    modules.flatMap((item) =>
+      item.permissions.map(
+        (permission) => [permission.key, permission] as const,
+      ),
+    ),
+  );
+  const featureKeys = new Set(
+    modules.flatMap((item) => item.features.map(({ key }) => key)),
+  );
+  for (const policy of module.dataPolicies || []) {
+    if (
+      !policy.key.trim() ||
+      !policy.resourceType.trim() ||
+      !policy.version.trim()
+    ) {
+      throw new Error("数据治理策略 Key、资源和版本不能为空");
+    }
+    if (!featureKeys.has(policy.featureKey)) {
+      throw new Error(
+        `${policy.key} 引用了未注册 Feature：${policy.featureKey}`,
+      );
+    }
+    const read = requiredPermission(
+      policy.key,
+      policy.readPermissionKey,
+      permissionByKey,
+    );
+    const reveal = requiredPermission(
+      policy.key,
+      policy.revealPermissionKey,
+      permissionByKey,
+    );
+    const exportPermission = requiredPermission(
+      policy.key,
+      policy.exportPermissionKey,
+      permissionByKey,
+    );
+    if (
+      read.action !== "read" ||
+      (read.accessRisk && read.accessRisk !== "standard")
+    ) {
+      throw new Error(`${policy.key} 普通读取权限必须是 standard read`);
+    }
+    if (
+      reveal.action !== "reveal" ||
+      reveal.accessRisk !== "sensitive-disclosure"
+    ) {
+      throw new Error(`${policy.key} 明文权限必须标记 sensitive-disclosure`);
+    }
+    if (
+      exportPermission.action !== "export" ||
+      exportPermission.accessRisk !== "governed-export"
+    ) {
+      throw new Error(`${policy.key} 导出权限必须标记 governed-export`);
+    }
+    if (!policy.fields.length)
+      throw new Error(`${policy.key} 至少治理一个字段`);
+    unique(
+      `${policy.key} 字段`,
+      policy.fields.map(({ fieldKey }) => fieldKey),
+    );
+    for (const field of policy.fields) validateGovernedField(policy.key, field);
+  }
+}
+
+function requiredPermission(
+  policyKey: string,
+  permissionKey: string,
+  definitions: ReadonlyMap<string, ModuleManifest["permissions"][number]>,
+) {
+  const permission = definitions.get(permissionKey);
+  if (!permission) {
+    throw new Error(`${policyKey} 引用了未注册权限：${permissionKey}`);
+  }
+  return permission;
+}
+
+function validateGovernedField(
+  policyKey: string,
+  field: NonNullable<ModuleManifest["dataPolicies"]>[number]["fields"][number],
+) {
+  if (!field.fieldKey.trim()) throw new Error(`${policyKey} 字段 Key 不能为空`);
+  if (field.mask.kind !== "partial") return;
+  if (
+    !Number.isSafeInteger(field.mask.prefix) ||
+    !Number.isSafeInteger(field.mask.suffix) ||
+    field.mask.prefix < 0 ||
+    field.mask.suffix < 0
+  ) {
+    throw new Error(`${policyKey}.${field.fieldKey} 掩码位数必须是非负整数`);
+  }
+}
+
+function validateDependencies(
+  modules: readonly ModuleManifest[],
+  moduleNames: ReadonlySet<string>,
+): string[] {
+  for (const module of modules) {
+    for (const dependency of module.dependencies || []) {
+      if (!moduleNames.has(dependency)) {
+        throw new Error(`模块 ${module.name} 缺少依赖：${dependency}`);
+      }
+    }
+  }
+  const pending = new Map(modules.map((module) => [module.name, module]));
+  const order: string[] = [];
+  while (pending.size) {
+    const ready = [...pending.values()].find((module) =>
+      (module.dependencies || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) throw new Error("模块依赖存在循环");
+    order.push(ready.name);
+    pending.delete(ready.name);
+  }
+  return order;
+}
+
+function validateReferences(
+  module: ModuleManifest,
+  permissions: ReadonlySet<string>,
+  features: ReadonlySet<string>,
+  audits: ReadonlySet<string>,
+): void {
+  const guarded = [
+    ...flattenMenus(module.menus),
+    ...module.adminRoutes,
+    ...module.apiPermissions,
+    ...module.tasks,
+    ...module.tools,
+    ...module.providers,
+  ];
+  for (const item of guarded) {
+    const reference = item as {
+      key?: string;
+      path?: string;
+      permissionKey?: string;
+      featureKey?: string;
+    };
+    const label = reference.key || reference.path || module.name;
+    if (reference.permissionKey && !permissions.has(reference.permissionKey)) {
+      throw new Error(`${label} 引用了未注册权限：${reference.permissionKey}`);
+    }
+    if (reference.featureKey && !features.has(reference.featureKey)) {
+      throw new Error(`${label} 引用了未注册 Feature：${reference.featureKey}`);
+    }
+  }
+  for (const tool of module.tools) {
+    if (!audits.has(tool.auditAction)) {
+      throw new Error(`${tool.key} 引用了未注册审计动作：${tool.auditAction}`);
+    }
+  }
+  for (const migration of module.migrations) {
+    if (migration.module !== module.name) {
+      throw new Error(
+        `Migration ${migration.id} 的模块归属应为 ${module.name}`,
+      );
+    }
+  }
+}
+
+function validateMenuRoutes(
+  menus: readonly MenuNode[],
+  routes: readonly ModuleManifest["adminRoutes"][number][],
+): void {
+  const byPath = new Map(routes.map((route) => [route.path, route]));
+  for (const menu of menus) {
+    if (!menu.path) continue;
+    const route = byPath.get(menu.path);
+    if (!route)
+      throw new Error(`菜单 ${menu.key} 缺少 Admin Route：${menu.path}`);
+    if (
+      route.directAccess !== "admin-admission" &&
+      (route.permissionKey !== menu.permissionKey ||
+        route.featureKey !== menu.featureKey)
+    ) {
+      throw new Error(`菜单 ${menu.key} 与 Admin Route Guard 不一致`);
+    }
+  }
+}
+
+function validateSchemaMigrations(
+  schemas: readonly ModuleManifest["schemaExports"][number][],
+): void {
+  for (const schema of schemas) {
+    if (!schema.migrationIds.length) {
+      throw new Error(`Schema Export ${schema.key} 缺少 Migration`);
+    }
+  }
+}
+
+function validateImplementations(
+  label: string,
+  declarations: readonly string[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const registered = unique(`${label} Handler`, implementations);
+  for (const key of declarations) {
+    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
+  }
+}
+
+function unique(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}
+
+function flattenMenus(menus: readonly MenuNode[]): MenuNode[] {
+  return menus.flatMap((menu) => [menu, ...flattenMenus(menu.children || [])]);
+}

package/src/manifest.ts

@@ -0,0 +1,92 @@
+import type {
+  ApiPermissionBinding,
+  AuditActionRegistration,
+  AuditActionType,
+  DataGovernancePolicyDefinition,
+  FeatureFlagDefinition,
+  MigrationBundle,
+  MigrationDefinition,
+  MenuNode,
+  PermissionDefinition,
+  SearchProviderManifestDefinition,
+} from "@southwind-ai/shared";
+
+export type { MigrationDefinition, MigrationDirection } from "@southwind-ai/shared";
+
+export interface ModuleToolDefinition {
+  key: string;
+  label: string;
+  description: string;
+  permissionKey: string;
+  featureKey?: string;
+  auditAction: AuditActionType;
+}
+
+export type AdminRouteSurface = "sidebar" | "account" | "hidden";
+
+export interface ModuleAdminRouteDefinition {
+  key: string;
+  path: string;
+  title: string;
+  surface: AdminRouteSurface;
+  directAccess?: "guarded" | "admin-admission" | "authenticated";
+  permissionKey?: string;
+  featureKey?: string;
+}
+
+export interface ModuleProviderDefinition {
+  key: string;
+  kind: string;
+  contractVersion: string;
+  permissionKey?: string;
+  featureKey?: string;
+}
+
+export interface ModuleSchemaExportDefinition {
+  key: string;
+  exportName: string;
+  migrationIds: readonly string[];
+}
+
+export interface ModuleScheduledTaskDefinition {
+  key: string;
+  label: string;
+  description: string;
+  permissionKey: string;
+  featureKey: string;
+  intervalSeconds: number;
+  maxAttempts: number;
+  retryDelaySeconds: number;
+}
+
+export interface ModuleManifest {
+  name: string;
+  version: string;
+  label: string;
+  description: string;
+  dependencies?: string[];
+  menus: MenuNode[];
+  adminRoutes: ModuleAdminRouteDefinition[];
+  permissions: PermissionDefinition[];
+  apiPermissions: ApiPermissionBinding[];
+  features: FeatureFlagDefinition[];
+  migrations: MigrationDefinition[];
+  migrationBundle?: MigrationBundle;
+  schemaExports: ModuleSchemaExportDefinition[];
+  tasks: ModuleScheduledTaskDefinition[];
+  tools: ModuleToolDefinition[];
+  providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
+  dataPolicies?: DataGovernancePolicyDefinition[];
+  auditActions: AuditActionRegistration[];
+  metadata?: Record<string, unknown>;
+}
+
+export type ModuleFactory = () => ModuleManifest;
+
+export interface ModuleImplementationBindings {
+  adminRoutes?: readonly string[];
+  apiRoutes?: readonly string[];
+  tasks?: readonly string[];
+  tools?: readonly string[];
+  providers?: readonly string[];
+}

package/src/menu-composition.ts

@@ -0,0 +1,54 @@
+import type { MenuNode } from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+export function composeModuleMenus(
+  modules: readonly ModuleManifest[],
+): MenuNode[] {
+  return mergeMenuNodes(modules.flatMap((module) => module.menus));
+}
+
+function mergeMenuNodes(nodes: readonly MenuNode[]): MenuNode[] {
+  const merged = new Map<string, MenuNode>();
+  for (const node of nodes) {
+    const current = merged.get(node.key);
+    if (!current) {
+      merged.set(node.key, cloneMenu(node));
+      continue;
+    }
+    assertSameMenuShell(current, node);
+    current.children = mergeMenuNodes([
+      ...(current.children || []),
+      ...(node.children || []),
+    ]);
+  }
+  return [...merged.values()].sort(
+    (left, right) =>
+      left.order - right.order || left.key.localeCompare(right.key),
+  );
+}
+
+function cloneMenu(node: MenuNode): MenuNode {
+  return {
+    ...node,
+    children: node.children ? mergeMenuNodes(node.children) : undefined,
+  };
+}
+
+function assertSameMenuShell(left: MenuNode, right: MenuNode): void {
+  const fields = [
+    "title",
+    "type",
+    "order",
+    "visible",
+    "path",
+    "component",
+    "icon",
+    "permissionKey",
+    "featureKey",
+  ] as const;
+  for (const field of fields) {
+    if (left[field] !== right[field]) {
+      throw new Error(`菜单目录 ${left.key} 的 ${field} 声明不一致`);
+    }
+  }
+}

package/src/registry.ts

@@ -0,0 +1,53 @@
+import type { ModuleFactory, ModuleManifest } from "./manifest.js";
+
+export interface ModuleRegistry {
+  register(factory: ModuleFactory): ModuleManifest;
+  list(): ModuleManifest[];
+  find(name: string): ModuleManifest | undefined;
+  clear(): void;
+}
+
+export function createModuleRegistry(): ModuleRegistry {
+  const modules = new Map<string, ModuleManifest>();
+
+  return {
+    register(factory) {
+      const manifest = factory();
+      if (modules.has(manifest.name)) {
+        throw new Error(`模块已注册：${manifest.name}`);
+      }
+
+      modules.set(manifest.name, manifest);
+      return manifest;
+    },
+    list() {
+      return Array.from(modules.values()).sort((a, b) =>
+        a.name.localeCompare(b.name),
+      );
+    },
+    find(name) {
+      return modules.get(name);
+    },
+    clear() {
+      modules.clear();
+    },
+  };
+}
+
+const defaultRegistry = createModuleRegistry();
+
+export function registerModule(factory: ModuleFactory): ModuleManifest {
+  return defaultRegistry.register(factory);
+}
+
+export function getModules(): ModuleManifest[] {
+  return defaultRegistry.list();
+}
+
+export function findModule(name: string): ModuleManifest | undefined {
+  return defaultRegistry.find(name);
+}
+
+export function clearModules(): void {
+  defaultRegistry.clear();
+}