create-windy 0.2.19 → 0.2.20

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

@@ -1,8 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
 import type { ModuleInitializer } from "@southwind-ai/server-sdk";
 // @windy-module work-order begin
-import { workOrderModuleInitializer } from "./example-modules.js";
+import { createWorkOrderModule } from "./example-modules.js";
 // @windy-module work-order end
 import { initializeModuleHosts } from "./module-host.js";
 // @windy-module work-order begin
@@ -13,88 +13,177 @@ import {
 // @windy-module work-order end
 
 describe("模块 Host 初始化", () => {
-  test("按安装顺序完成初始化后再创建运行时注册表", async () => {
-    const events: string[] = [];
-    const first = initializer("alpha", async (host) => {
-      events.push("alpha:start");
-      await Promise.resolve();
-      host.registerDurableHandler({
-        key: "alpha.refresh",
-        payload: { parse: () => ({}) },
-        execute: () => undefined,
-      });
-      events.push("alpha:end");
-    });
-    const second = initializer("beta", () => {
-      events.push("beta");
-    });
+  test("任务、工具、角色预设与 Provider 注册强制命名空间与 Manifest 声明", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerTaskHandlers([
+              { taskKey: "other.snapshot", handler: () => undefined },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("定时任务不属于模块 known：other.snapshot");
 
-    const initialized = await initializeModuleHosts({
-      modules: [{ name: "alpha" }, { name: "beta" }],
-      initializers: [first, second],
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerTaskHandlers([
+              { taskKey: "known.snapshot", handler: () => undefined },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("定时任务 Handler 未在 Manifest 声明：known.snapshot");
+
+    const withTask = manifest("known", {
+      tasks: [
+        {
+          key: "known.snapshot",
+          label: "快照",
+          description: "",
+          permissionKey: "known.item.read",
+          featureKey: "known.feature",
+          intervalSeconds: 60,
+          maxAttempts: 3,
+          retryDelaySeconds: 10,
+        },
+      ],
     });
-    expect(events).toEqual(["alpha:start", "alpha:end", "beta"]);
+    await expect(
+      initializeModuleHosts({
+        modules: [withTask],
+        initializers: [
+          initializer("known", (host) => {
+            const registration = {
+              taskKey: "known.snapshot",
+              handler: () => undefined,
+            };
+            host.registerTaskHandlers([registration, registration]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("定时任务 Handler 重复注册：known.snapshot");
 
-    const registry = new DurableHandlerRegistry();
-    initialized.installDurableHandlers(registry);
-    expect(registry.keys()).toEqual(["alpha.refresh"]);
-  });
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerToolHandlers([
+              {
+                toolKey: "other.list",
+                scopeMode: "platform",
+                execute: () => ({ items: [], total: 0, page: 1, pageSize: 10 }),
+              },
+            ]);
+          }),
+        ],
+      }),
+    ).rejects.toThrow("Agent Tool不属于模块 known：other.list");
 
-  test("未知模块、错误命名空间和重复注册立即失败", async () => {
     await expect(
       initializeModuleHosts({
-        modules: [{ name: "known" }],
-        initializers: [initializer("missing", () => undefined)],
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerToolHandlers([
+              {
+                toolKey: "known.list",
+                scopeMode: "platform",
+                execute: () => ({ items: [], total: 0, page: 1, pageSize: 10 }),
+              },
+            ]);
+          }),
+        ],
       }),
-    ).rejects.toThrow("模块初始化器与已安装模块不匹配：missing");
+    ).rejects.toThrow("Agent Tool Handler 未在 Manifest 声明：known.list");
 
     await expect(
       initializeModuleHosts({
-        modules: [{ name: "known" }],
+        modules: [
+          manifest("known", {
+            permissions: [permission("known.item.read", "known")],
+          }),
+        ],
         initializers: [
           initializer("known", (host) => {
-            host.registerUploadPolicy(policy("other.attachment"));
+            host.registerRolePresets([
+              {
+                key: "known.manager",
+                label: "管理员",
+                permissionKeys: ["other.item.read"],
+              },
+            ]);
           }),
         ],
       }),
-    ).rejects.toThrow("上传用途不属于模块 known：other.attachment");
+    ).rejects.toThrow("角色预设权限不属于模块 known：other.item.read");
 
     await expect(
       initializeModuleHosts({
-        modules: [{ name: "known" }],
+        modules: [manifest("known")],
         initializers: [
           initializer("known", (host) => {
-            host.registerUploadPolicy(policy("known.attachment"));
-            host.registerUploadPolicy(policy("known.attachment"));
+            host.registerRolePresets([
+              {
+                key: "known.manager",
+                label: "管理员",
+                permissionKeys: ["known.item.manage"],
+              },
+            ]);
           }),
         ],
       }),
-    ).rejects.toThrow("上传用途重复注册：known.attachment");
+    ).rejects.toThrow("角色预设引用了模块 known 未声明权限：known.item.manage");
 
     await expect(
       initializeModuleHosts({
-        modules: [],
-        initializers: [],
-        baseUploadPolicies: [policy("platform.file"), policy("platform.file")],
+        modules: [manifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerSearchProviders([
+              {
+                key: "other.search",
+                providerVersion: "0.1.0",
+                search: () => Promise.resolve({ hits: [] }),
+                health: () =>
+                  Promise.resolve({
+                    status: "healthy",
+                    checkedAt: new Date().toISOString(),
+                  }),
+              },
+            ]);
+          }),
+        ],
       }),
-    ).rejects.toThrow("上传用途重复注册：platform.file");
+    ).rejects.toThrow("搜索 Provider不属于模块 known：other.search");
 
     await expect(
       initializeModuleHosts({
-        modules: [{ name: "known" }],
+        modules: [manifest("known")],
         initializers: [
           initializer("known", (host) => {
-            const definition = {
-              key: "known.refresh",
-              payload: { parse: () => ({}) },
-              execute: () => undefined,
-            };
-            host.registerDurableHandler(definition);
-            host.registerDurableHandler(definition);
+            host.registerSearchProviders([
+              {
+                key: "known.search",
+                providerVersion: "0.1.0",
+                search: () => Promise.resolve({ hits: [] }),
+                health: () =>
+                  Promise.resolve({
+                    status: "healthy",
+                    checkedAt: new Date().toISOString(),
+                  }),
+              },
+            ]);
           }),
         ],
       }),
-    ).rejects.toThrow("任务 handler 重复注册：known.refresh");
+    ).rejects.toThrow("搜索 Provider 未在 Manifest 声明：known.search");
   });
 
   // @windy-module work-order begin
@@ -110,9 +199,10 @@ describe("模块 Host 初始化", () => {
       ),
     ).toBe(false);
 
+    const workOrder = createWorkOrderModule();
     const withWorkOrder = await initializeModuleHosts({
-      modules: [{ name: "work-order" }],
-      initializers: [workOrderModuleInitializer],
+      modules: [workOrder.manifest],
+      installations: [workOrder],
       baseUploadPolicies: platformUploadPolicies,
     });
     const storage = createStorageRuntime(
@@ -129,6 +219,35 @@ describe("模块 Host 初始化", () => {
     });
     expect(session.purpose).toBe("work-order.ticket.attachment");
   });
+
+  test("work-order 初始化器声明式注册路由、任务、Provider 与角色预设", async () => {
+    const workOrder = createWorkOrderModule();
+    const initialized = await initializeModuleHosts({
+      modules: [workOrder.manifest],
+      installations: [workOrder],
+    });
+
+    expect(
+      initialized.routes.map(
+        ({ definition }) => `${definition.method} ${definition.path}`,
+      ),
+    ).toEqual([
+      "GET /api/work-orders",
+      "GET /api/work-orders/:id",
+      "POST /api/work-orders",
+      "PUT /api/work-orders/:id",
+      "DELETE /api/work-orders/:id",
+    ]);
+    expect(
+      initialized.taskHandlers.map(({ registration }) => registration.taskKey),
+    ).toEqual(["work-order.ticket.snapshot"]);
+    expect(
+      initialized.searchProviders.map(({ provider }) => provider.key),
+    ).toEqual(["work-order.ticket.search"]);
+    expect(initialized.rolePresets.map(({ preset }) => preset.key)).toEqual([
+      "work-order.ticket-manager",
+    ]);
+  });
   // @windy-module work-order end
 });
 
@@ -139,13 +258,38 @@ function initializer(
   return { moduleName, initialize };
 }
 
-function policy(purpose: string) {
+function manifest(
+  name: string,
+  overrides: Partial<ModuleManifest> = {},
+): ModuleManifest {
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} 模块`,
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+    ...overrides,
+  };
+}
+
+function permission(key: string, module: string) {
   return {
-    purpose,
-    maxByteSize: 1024,
-    maxPartByteSize: 512,
-    sessionTtlMs: 60_000,
-    allowedTypes: { "text/plain": ["txt"] },
-    signature: "none" as const,
+    key,
+    label: key,
+    module,
+    moduleLabel: module,
+    resource: "item",
+    resourceLabel: "事项",
+    action: "read" as const,
   };
 }

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

@@ -1,113 +1,34 @@
-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,
+} 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/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(