create-windy 0.2.19 → 0.2.21

package/template/apps/server/src/module-host.ts

@@ -1,113 +1,35 @@
-import {
-  DurableHandlerRegistry,
-  type DurableHandlerDefinition,
-} from "@southwind-ai/jobs";
-import type {
-  ModuleHost,
-  ModuleInitializer,
-  ModuleUploadPolicy,
-} from "@southwind-ai/server-sdk";
-
-interface InstalledModule {
-  name: string;
-}
-
-export interface InitializeModuleHostsInput {
-  modules: readonly InstalledModule[];
-  initializers: readonly ModuleInitializer[];
-  baseUploadPolicies?: readonly ModuleUploadPolicy[];
-}
-
-export interface InitializedModuleHosts {
-  readonly uploadPolicies: readonly ModuleUploadPolicy[];
-  installDurableHandlers(registry: DurableHandlerRegistry): void;
-}
-
-type HandlerInstaller = (registry: DurableHandlerRegistry) => void;
-
-export async function initializeModuleHosts(
-  input: InitializeModuleHostsInput,
-): Promise<InitializedModuleHosts> {
-  const installedNames = new Set(input.modules.map(({ name }) => name));
-  const initializedNames = new Set<string>();
-  const uploadPolicies: ModuleUploadPolicy[] = [];
-  const uploadPurposes = new Set<string>();
-  for (const policy of input.baseUploadPolicies ?? []) {
-    if (uploadPurposes.has(policy.purpose)) {
-      throw new Error(`上传用途重复注册：${policy.purpose}`);
-    }
-    uploadPurposes.add(policy.purpose);
-    uploadPolicies.push(policy);
-  }
-  const handlerKeys = new Set<string>();
-  const handlerInstallers: HandlerInstaller[] = [];
-
-  for (const initializer of input.initializers) {
-    const moduleName = initializer.moduleName.trim();
-    if (!installedNames.has(moduleName)) {
-      throw new Error(`模块初始化器与已安装模块不匹配：${moduleName}`);
-    }
-    if (initializedNames.has(moduleName)) {
-      throw new Error(`模块初始化器重复注册：${moduleName}`);
-    }
-    initializedNames.add(moduleName);
-    await initializer.initialize(
-      createScopedHost({
-        moduleName,
-        uploadPolicies,
-        uploadPurposes,
-        handlerKeys,
-        handlerInstallers,
-      }),
-    );
-  }
-
-  return {
-    uploadPolicies: [...uploadPolicies],
-    installDurableHandlers(registry) {
-      for (const install of handlerInstallers) install(registry);
-    },
-  };
-}
-
-interface ScopedHostState {
-  moduleName: string;
-  uploadPolicies: ModuleUploadPolicy[];
-  uploadPurposes: Set<string>;
-  handlerKeys: Set<string>;
-  handlerInstallers: HandlerInstaller[];
-}
-
-function createScopedHost(state: ScopedHostState): ModuleHost {
-  return {
-    moduleName: state.moduleName,
-    registerUploadPolicy(policy) {
-      requireModuleNamespace("上传用途", policy.purpose, state.moduleName);
-      if (state.uploadPurposes.has(policy.purpose)) {
-        throw new Error(`上传用途重复注册：${policy.purpose}`);
-      }
-      state.uploadPurposes.add(policy.purpose);
-      state.uploadPolicies.push(policy);
-    },
-    registerDurableHandler<T>(definition: DurableHandlerDefinition<T>) {
-      requireModuleNamespace("任务 handler", definition.key, state.moduleName);
-      if (state.handlerKeys.has(definition.key)) {
-        throw new Error(`任务 handler 重复注册：${definition.key}`);
-      }
-      state.handlerKeys.add(definition.key);
-      state.handlerInstallers.push((registry) => {
-        registry.register(definition);
-      });
-    },
-  };
-}
-
-function requireModuleNamespace(
-  kind: string,
-  value: string,
-  moduleName: string,
-): void {
-  if (value !== moduleName && !value.startsWith(`${moduleName}.`)) {
-    throw new Error(`${kind}不属于模块 ${moduleName}：${value}`);
-  }
-}
+export {
+  initializeModuleHosts,
+  type InitializedModuleHosts,
+  type InitializeModuleHostsInput,
+  type RegisteredModuleRolePreset,
+  type RegisteredModuleRoute,
+  type RegisteredModuleSearchProvider,
+  type RegisteredModuleTaskHandler,
+  type RegisteredModuleToolHandler,
+  type RegisteredModuleAiOperationHandler,
+} from "./module-host/initialize.js";
+export {
+  buildModuleRequestContext,
+  requestActorFromModule,
+  toModuleActor,
+} from "./module-host/request-context.js";
+export {
+  installModuleRoutes,
+  type ModuleRouteInstallContext,
+} from "./module-host/route-installer.js";
+export {
+  moduleRolePresetId,
+  synchronizeModuleRolePresets,
+} from "./module-host/role-presets.js";
+export {
+  adaptModuleSearchProvider,
+  adaptModuleSearchProviders,
+} from "./module-host/search-providers.js";
+export {
+  createModuleStoragePort,
+  type ModuleStorageScope,
+  type ModuleStorageServices,
+} from "./module-host/storage-port.js";
+export { createModuleTaskDefinitions } from "./module-host/task-definitions.js";
+export { createModuleToolHandlerMap } from "./module-host/tool-handlers.js";

package/template/apps/server/src/module-runtime-validation.ts

@@ -0,0 +1,40 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleToolHandlers } from "./agent/routes.js";
+import { validateServerModuleComposition } from "./module-composition.js";
+import type { InitializedModuleHosts } from "./module-host.js";
+
+export function validateInstalledRuntime(input: {
+  modules: ModuleManifest[];
+  routes: readonly { method: string; path: string }[];
+  tasks: readonly { key: string }[];
+  tools: ModuleToolHandlers;
+  providers: readonly string[];
+  hosts: InitializedModuleHosts;
+}): void {
+  const aiOperations = input.hosts.aiOperationHandlers.map(
+    ({ registration }) => registration.operationKey,
+  );
+  validateServerModuleComposition({
+    modules: input.modules,
+    routes: input.routes,
+    tasks: input.tasks,
+    tools: input.tools,
+    aiOperations,
+    providers: input.providers,
+    moduleRegistrations: {
+      routes: input.hosts.routes.map(
+        ({ definition }) => `${definition.method} ${definition.path}`,
+      ),
+      tasks: input.hosts.taskHandlers.map(
+        ({ registration }) => registration.taskKey,
+      ),
+      tools: input.hosts.toolHandlers.map(
+        ({ registration }) => registration.toolKey,
+      ),
+      aiOperations,
+      providers: input.hosts.searchProviders.map(
+        ({ provider }) => provider.key,
+      ),
+    },
+  });
+}

package/template/apps/server/src/route-guards.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { entitlementKey, featureKey } from "@southwind-ai/shared";
+import {
+  entitlementKey,
+  featureKey,
+  licenseVersionKey,
+} from "@southwind-ai/shared";
 import { evaluateAccessGuards } from "./access-guards.js";
 import { createServerRuntime } from "./runtime.js";
 
@@ -81,6 +85,113 @@ describe("access guard pipeline", () => {
     expect("edition" in context.license!).toBe(false);
   });
 
+  test("Feature 依赖未启用时拒绝并记录 security.denied，依赖启用后放行", async () => {
+    const dependency = {
+      key: featureKey("business.base"),
+      label: "业务基础",
+      module: "business",
+      visible: "visible" as const,
+      enabled: true,
+      stage: "stable" as const,
+    };
+    const capability = {
+      ...dependency,
+      key: featureKey("business.report"),
+      dependencies: [dependency.key],
+    };
+    let dependencyEnabled = false;
+    const runtime = createServerRuntime(
+      {},
+      {
+        actorResolver: { resolve: () => actor(["business.report.read"]) },
+        licenseResolver: { resolve: () => ({ entitlements: [] }) },
+        featureCatalog: [dependency, capability],
+        featureResolver: {
+          resolve: (key) => ({
+            key,
+            enabled: key === dependency.key ? dependencyEnabled : true,
+            visible: "visible" as const,
+          }),
+        },
+      },
+    );
+    const policy = {
+      permission: { permissionKey: "business.report.read" },
+      feature: capability,
+    };
+
+    const deniedContext = await runtime.createGuardContext(
+      new Request("http://local"),
+    );
+    const denied = await evaluateAccessGuards(runtime, deniedContext, policy);
+
+    expect(denied.decision.reason).toBe("dependency-missing");
+    expect(denied.feature?.auditEvent?.action).toBe("security.denied");
+    const auditEvents = await runtime.listAuditEvents({
+      page: 1,
+      pageSize: 10,
+    });
+    expect(
+      auditEvents.items.some(
+        (event) =>
+          event.action === "security.denied" &&
+          event.target?.id === "business.report",
+      ),
+    ).toBe(true);
+
+    dependencyEnabled = true;
+    const allowedContext = await runtime.createGuardContext(
+      new Request("http://local"),
+    );
+    const allowed = await evaluateAccessGuards(runtime, allowedContext, policy);
+
+    expect(allowed.decision.reason).toBe("allowed");
+  });
+
+  test("Feature 依赖不在当前 License 版本内时 fail closed", async () => {
+    const dependency = {
+      key: featureKey("business.advanced-base"),
+      label: "高级业务基础",
+      module: "business",
+      visible: "visible" as const,
+      enabled: true,
+      stage: "stable" as const,
+      allowedLicenseVersions: [licenseVersionKey("advanced")],
+    };
+    const capability = {
+      ...dependency,
+      key: featureKey("business.report"),
+      allowedLicenseVersions: [licenseVersionKey("standard")],
+      dependencies: [dependency.key],
+    };
+    const runtime = createServerRuntime(
+      {},
+      {
+        actorResolver: { resolve: () => actor(["business.report.read"]) },
+        licenseResolver: {
+          resolve: () => ({
+            versionKey: licenseVersionKey("standard"),
+            entitlements: [],
+          }),
+        },
+        featureCatalog: [dependency, capability],
+        featureResolver: {
+          resolve: (key) => ({ key, enabled: true, visible: "visible" }),
+        },
+      },
+    );
+    const context = await runtime.createGuardContext(
+      new Request("http://local"),
+    );
+
+    const result = await evaluateAccessGuards(runtime, context, {
+      permission: { permissionKey: "business.report.read" },
+      feature: capability,
+    });
+
+    expect(result.decision.reason).toBe("dependency-missing");
+  });
+
   test("缺少 Entitlement 时不读取 Feature 状态，开关不能绕过商业授权", async () => {
     let featureResolveCount = 0;
     const runtime = createServerRuntime(

package/template/apps/server/src/runtime-feature.ts

@@ -1,4 +1,10 @@
-import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import {
+  isLicenseVersionAllowed,
+  resolveFeatureState,
+  type FeatureFlagDefinition,
+  type FeatureFlagState,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "./guards.js";
 
 export interface FeatureFlagRuntimeResolver {
   resolve(
@@ -16,11 +22,16 @@ export interface FeatureFlagRuntimeState {
   allowedLicenseVersions?: FeatureFlagDefinition["allowedLicenseVersions"];
 }
 
+/** 运行时解析后的 Feature；disabledReason 复用 shared resolveFeatureState 语义。 */
+export interface ResolvedFeatureFlag extends FeatureFlagDefinition {
+  disabledReason?: FeatureFlagState["reason"];
+}
+
 export class RuntimeFeatureCatalog {
   private readonly definitions = new Map<string, FeatureFlagDefinition>();
   private readonly requestCache = new WeakMap<
     object,
-    Map<string, FeatureFlagDefinition>
+    Map<string, ResolvedFeatureFlag>
   >();
 
   constructor(
@@ -34,18 +45,18 @@ export class RuntimeFeatureCatalog {
   }
 
   resolve(
-    context: object,
+    context: RequestGuardContext,
     manifestFeature: FeatureFlagDefinition,
-  ): Promise<FeatureFlagDefinition> {
+  ): Promise<ResolvedFeatureFlag> {
     this.definitions.set(manifestFeature.key, manifestFeature);
     return this.resolveInternal(context, manifestFeature, new Set());
   }
 
   private async resolveInternal(
-    context: object,
+    context: RequestGuardContext,
     manifestFeature: FeatureFlagDefinition,
     visiting: ReadonlySet<string>,
-  ): Promise<FeatureFlagDefinition> {
+  ): Promise<ResolvedFeatureFlag> {
     const cache = this.cacheFor(context);
     const cached = cache.get(manifestFeature.key);
     if (cached) return cached;
@@ -53,33 +64,42 @@ export class RuntimeFeatureCatalog {
       return disabledFeature(manifestFeature);
     }
 
-    const resolved = await this.resolveOwnState(manifestFeature);
-    if (!resolved.enabled || !manifestFeature.dependencies?.length) {
-      cache.set(manifestFeature.key, resolved);
-      return resolved;
-    }
-
-    const nextVisiting = new Set(visiting);
-    nextVisiting.add(manifestFeature.key);
-    for (const dependencyKey of manifestFeature.dependencies) {
-      const dependency = this.definitions.get(dependencyKey);
-      if (!dependency) {
-        const disabled = disabledFeature(resolved);
-        cache.set(manifestFeature.key, disabled);
-        return disabled;
-      }
-      const dependencyState = await this.resolveInternal(
-        context,
-        dependency,
-        nextVisiting,
-      );
-      if (!dependencyState.enabled || dependencyState.visible !== "visible") {
-        const disabled = { ...resolved, enabled: false };
-        cache.set(manifestFeature.key, disabled);
-        return disabled;
+    const own = await this.resolveOwnState(manifestFeature);
+    // dependencies 来自 manifest；启用集合取运行时解析后的依赖状态，
+    // 最终判定统一交给 shared resolveFeatureState，避免第二套漂移逻辑。
+    const enabledDependencies = new Set<string>();
+    if (
+      own.enabled &&
+      own.visible === "visible" &&
+      manifestFeature.dependencies?.length
+    ) {
+      const nextVisiting = new Set(visiting);
+      nextVisiting.add(manifestFeature.key);
+      for (const dependencyKey of manifestFeature.dependencies) {
+        const dependency = this.definitions.get(dependencyKey);
+        if (!dependency) continue;
+        const dependencyState = await this.resolveInternal(
+          context,
+          dependency,
+          nextVisiting,
+        );
+        if (
+          dependencyState.enabled &&
+          dependencyState.visible === "visible" &&
+          isFeatureLicensedForContext(dependencyState, context)
+        ) {
+          enabledDependencies.add(dependencyKey);
+        }
       }
     }
 
+    const state = resolveFeatureState(own, enabledDependencies, true);
+    const resolved: ResolvedFeatureFlag = {
+      ...own,
+      enabled: state.enabled,
+      visible: state.visible,
+      ...(state.reason ? { disabledReason: state.reason } : {}),
+    };
     cache.set(manifestFeature.key, resolved);
     return resolved;
   }
@@ -108,7 +128,9 @@ export class RuntimeFeatureCatalog {
     }
   }
 
-  private cacheFor(context: object): Map<string, FeatureFlagDefinition> {
+  private cacheFor(
+    context: RequestGuardContext,
+  ): Map<string, ResolvedFeatureFlag> {
     let cache = this.requestCache.get(context);
     if (!cache) {
       cache = new Map();
@@ -118,6 +140,19 @@ export class RuntimeFeatureCatalog {
   }
 }
 
+function isFeatureLicensedForContext(
+  feature: FeatureFlagDefinition,
+  context: RequestGuardContext,
+): boolean {
+  return (
+    isLicenseVersionAllowed(feature, context.license?.versionKey) &&
+    (!feature.requiredEntitlement ||
+      Boolean(
+        context.license?.entitlements?.includes(feature.requiredEntitlement),
+      ))
+  );
+}
+
 function disabledFeature(
   feature: FeatureFlagDefinition,
 ): FeatureFlagDefinition {

package/template/apps/server/src/runtime.test.ts

@@ -273,6 +273,7 @@ describe("server runtime", () => {
     expect(await runtime.resolveFeature(context, capability)).toMatchObject({
       enabled: false,
       visible: "visible",
+      disabledReason: "dependency-missing",
     });
   });
 

package/template/apps/server/src/runtime.ts

@@ -25,11 +25,13 @@ import { developmentAdminActor } from "./runtime-development.js";
 import {
   RuntimeFeatureCatalog,
   type FeatureFlagRuntimeResolver,
+  type ResolvedFeatureFlag,
 } from "./runtime-feature.js";
 
 export type {
   FeatureFlagRuntimeResolver,
   FeatureFlagRuntimeState,
+  ResolvedFeatureFlag,
 } from "./runtime-feature.js";
 
 export interface SessionRecord {
@@ -230,7 +232,7 @@ export function createServerRuntime(
     async resolveFeature(
       context: ReturnType<typeof createRequestGuardContext>,
       manifestFeature: FeatureFlagDefinition,
-    ): Promise<FeatureFlagDefinition> {
+    ): Promise<ResolvedFeatureFlag> {
       return featureCatalog.resolve(context, manifestFeature);
     },
     recordDecisions(decisions: Array<GuardDecision | undefined>) {

package/template/apps/server/src/system/built-in-roles.ts

@@ -90,7 +90,7 @@ function role(
   };
 }
 
-function menuKeysForPermissions(
+export function menuKeysForPermissions(
   snapshot: FoundationSnapshot,
   permissions: string[],
 ): string[] {

package/template/apps/server/src/work-order/foundation-modules.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { featureKey } from "@southwind-ai/shared";
+import { validateCapabilityCatalogs } from "@southwind-ai/modules";
 import {
   createFoundationSnapshot,
   loadFoundationModules,
 } from "../foundation.js";
-import { createExampleModuleRuntime } from "../example-modules.js";
-import type { ManagedDepartment } from "../system/entities.js";
-import { InMemoryEntityRepository } from "../system/repository.js";
+import { createWorkOrderModule } from "../example-modules.js";
+import {
+  adaptModuleSearchProviders,
+  initializeModuleHosts,
+} from "../module-host.js";
 
 describe("平台模块 composition root", () => {
   test("默认安装平台能力模块与可删除的工单模块", () => {
@@ -47,6 +50,21 @@ describe("平台模块 composition root", () => {
     );
   });
 
+  test("示例工单的合法 Migration Bundle 通过启动校验", () => {
+    const modules = loadFoundationModules();
+    const workOrder = modules.find(({ name }) => name === "work-order");
+
+    expect(() => validateCapabilityCatalogs(modules)).not.toThrow();
+    expect(workOrder?.migrationBundle?.migrations.map(({ id }) => id)).toEqual([
+      "work-order.0001.create-work-orders",
+    ]);
+    expect(
+      workOrder?.migrationBundle?.migrations.every(({ checksum }) =>
+        checksum.startsWith("sha256:"),
+      ),
+    ).toBe(true);
+  });
+
   test("业务 API 的 package 依赖图不经过 Windy Web 或 Vue", async () => {
     const serverPackage = await packageJson(
       new URL("../../package.json", import.meta.url),
@@ -66,21 +84,23 @@ describe("平台模块 composition root", () => {
     });
     expect(serverPackage.dependencies).not.toHaveProperty("@southwind-ai/web");
     expect(serverPackage.dependencies).not.toHaveProperty("vue");
-    expect(businessPackage.dependencies).not.toHaveProperty("@southwind-ai/web");
+    expect(businessPackage.dependencies).not.toHaveProperty(
+      "@southwind-ai/web",
+    );
     expect(businessPackage.dependencies).not.toHaveProperty("vue");
     expect(webPackage.dependencies).not.toHaveProperty(
       "@southwind-ai/example-work-order",
     );
   });
 
-  test("示例模块运行时从同一 composition seam 提供搜索 Handler", () => {
-    const snapshot = createFoundationSnapshot();
-    const runtime = createExampleModuleRuntime({
-      features: snapshot.features,
-      departments: new InMemoryEntityRepository<ManagedDepartment>(),
+  test("示例模块经 Host 声明式装配提供搜索 Provider", async () => {
+    const module = createWorkOrderModule();
+    const hosts = await initializeModuleHosts({
+      modules: [module.manifest],
+      installations: [module],
     });
 
-    expect(runtime?.providers.map(({ key }) => key)).toEqual([
+    expect(adaptModuleSearchProviders(hosts).map(({ key }) => key)).toEqual([
       "work-order.ticket.search",
     ]);
   });

package/template/apps/server/src/work-order/routes.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import type { WorkOrder } from "@southwind-ai/example-work-order";
+import {
+  workOrderModule,
+  type WorkOrder,
+} from "@southwind-ai/example-work-order";
 import { licenseVersionKey } from "@southwind-ai/shared";
+import { initializeModuleHosts, installModuleRoutes } from "../module-host.js";
+import { createWorkOrderModule } from "../example-modules.js";
 import { InMemoryEntityRepository } from "../system/repository.js";
 import { InMemoryScopedEntityRepository } from "../data-access/scoped-repository.js";
 import { buildScopeContext } from "../data-access/context.js";
@@ -8,8 +13,6 @@ import type { ManagedDepartment } from "../system/entities.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import { createServerRuntime } from "../runtime.js";
 import type { RequestActor } from "../guards.js";
-import { registerWorkOrderRoutes } from "./routes.js";
-import { WorkOrderService } from "./service.js";
 import { workOrderDataScopeBinding } from "./repository.js";
 
 describe("示例工单 routes", () => {
@@ -39,6 +42,9 @@ describe("示例工单 routes", () => {
     expect(await reason(rbacDenied.invoke("GET", "/work-orders"))).toBe(
       "missing-permission",
     );
+    expect(
+      rbacDenied.runtime.auditSink.list().map(({ action }) => action),
+    ).toContain("security.denied");
 
     const licenseDenied = await createFixture({ licenseVersion: "basic" });
     expect(await reason(licenseDenied.invoke("GET", "/work-orders"))).toBe(
@@ -100,23 +106,29 @@ async function createFixture(options: FixtureOptions = {}) {
       },
     },
   );
+  const module = createWorkOrderModule();
+  const hosts = await initializeModuleHosts({
+    modules: [module.manifest],
+    installations: [module],
+  });
+  module.attach({
+    departments: new InMemoryEntityRepository<ManagedDepartment>([
+      department("dept_a"),
+      department("dept_b"),
+    ]),
+    repository: new InMemoryScopedEntityRepository<WorkOrder>(
+      [
+        ticket("ticket_self", "user_self", "dept_a"),
+        ticket("ticket_other", "user_other", "dept_b"),
+      ],
+      workOrderDataScopeBinding,
+    ),
+  });
   const app = new FakeRouteApp();
-  const workOrders = new InMemoryScopedEntityRepository<WorkOrder>(
-    [
-      ticket("ticket_self", "user_self", "dept_a"),
-      ticket("ticket_other", "user_other", "dept_b"),
-    ],
-    workOrderDataScopeBinding,
-  );
-  const departments = new InMemoryEntityRepository<ManagedDepartment>([
-    department("dept_a"),
-    department("dept_b"),
-  ]);
-  registerWorkOrderRoutes(
-    app,
-    new WorkOrderService(workOrders, departments),
+  installModuleRoutes(hosts, app, {
     runtime,
-  );
+    features: workOrderModule().features,
+  });
   const guardContext = await runtime.createGuardContext(
     new Request("http://localhost/api/work-orders"),
   );