create-windy 0.2.19 → 0.2.21

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

@@ -0,0 +1,165 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleInitializer } from "@southwind-ai/server-sdk";
+import type { FileMetadata, UploadPolicy } from "@southwind-ai/storage";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { createModuleStoragePort } from "./storage-port.js";
+import { manifest } from "./test-fixtures.js";
+
+const SHOP_POLICY = policy("shop.attachment");
+const OTHER_POLICY = policy("other.attachment");
+
+describe("模块受限 Upload/BlobRead Port", () => {
+  test("本模块用途可以创建上传会话，Owner 由宿主补齐", async () => {
+    const { port } = setup();
+    const session = await port.createUploadSession({
+      purpose: "shop.attachment",
+      filename: "现场照片.txt",
+      mimeType: "text/plain",
+      expectedByteSize: 3,
+    });
+
+    expect(session.ownerId).toBe("user_shop");
+    expect(session.purpose).toBe("shop.attachment");
+  });
+
+  test("跨模块与平台用途创建会话被拒绝", async () => {
+    const { port } = setup();
+
+    await expect(
+      port.createUploadSession({
+        purpose: "other.attachment",
+        filename: "a.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 3,
+      }),
+    ).rejects.toThrow("上传用途不属于模块 shop：other.attachment");
+
+    await expect(
+      port.createUploadSession({
+        purpose: "bulk-data",
+        filename: "a.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 3,
+      }),
+    ).rejects.toThrow("上传用途不属于模块 shop：bulk-data");
+  });
+
+  test("文件读取保持 Owner 约束", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_other", "shop.attachment");
+
+    await expect(port.openFile(file.id)).rejects.toThrow("无权访问该文件");
+
+    const ownerPort = createModuleStoragePort(
+      { uploads: storage.uploads, files: storage.files },
+      {
+        moduleName: "shop",
+        ownerId: "user_other",
+        purposes: new Set(["shop.attachment"]),
+      },
+    );
+    const opened = await ownerPort.openFile(file.id);
+    expect(opened.id).toBe(file.id);
+  });
+
+  test("Own 文件但用途越界时读取被拒绝", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_shop", "other.attachment");
+
+    await expect(port.openFile(file.id)).rejects.toThrow(
+      "上传用途不属于模块 shop：other.attachment",
+    );
+  });
+
+  test("公开读取强制用途属于本模块", async () => {
+    const { storage, port } = setup();
+    const file = await seedFile(storage, "user_shop", "shop.attachment");
+
+    await expect(port.openPublicFile(file.id, "bulk-data")).rejects.toThrow(
+      "上传用途不属于模块 shop：bulk-data",
+    );
+    const opened = await port.openPublicFile(file.id, "shop.attachment");
+    expect(opened.id).toBe(file.id);
+  });
+
+  test("命名空间重叠模块注册同一用途在启动时失败", async () => {
+    const initializer = (
+      moduleName: string,
+      register: ModuleInitializer["initialize"],
+    ): ModuleInitializer => ({ moduleName, initialize: register });
+
+    await expect(
+      initializeModuleHosts({
+        modules: [manifest("shop"), manifest("shop.sub")],
+        initializers: [
+          initializer("shop", (host) => {
+            host.registerUploadPolicy(policy("shop.sub"));
+          }),
+          initializer("shop.sub", (host) => {
+            host.registerUploadPolicy(policy("shop.sub"));
+          }),
+        ],
+      }),
+    ).rejects.toThrow("上传用途重复注册：shop.sub");
+  });
+});
+
+function setup() {
+  const storage = createStorageRuntime({}, undefined, [
+    SHOP_POLICY,
+    OTHER_POLICY,
+  ]);
+  const port = createModuleStoragePort(
+    { uploads: storage.uploads, files: storage.files },
+    {
+      moduleName: "shop",
+      ownerId: "user_shop",
+      purposes: new Set(["shop.attachment"]),
+    },
+  );
+  return { storage, port };
+}
+
+function policy(purpose: string): UploadPolicy {
+  return {
+    purpose,
+    maxByteSize: 1024,
+    maxPartByteSize: 512,
+    sessionTtlMs: 60_000,
+    allowedTypes: { "text/plain": ["txt"] },
+    signature: "none",
+  };
+}
+
+async function seedFile(
+  storage: ReturnType<typeof createStorageRuntime>,
+  ownerId: string,
+  purpose: string,
+): Promise<FileMetadata> {
+  const data = new TextEncoder().encode("abc");
+  const sha256 = new Bun.CryptoHasher("sha256").update(data).digest("hex");
+  const session = await storage.uploads.create({
+    ownerId,
+    purpose,
+    filename: "a.txt",
+    mimeType: "text/plain",
+    expectedByteSize: data.length,
+    expectedSha256: sha256,
+  });
+  await storage.uploads.appendPart({
+    sessionId: session.id,
+    ownerId,
+    partNumber: 0,
+    byteOffset: 0,
+    byteSize: data.length,
+    sha256,
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(data);
+        controller.close();
+      },
+    }),
+  });
+  return storage.uploads.complete(session.id, ownerId);
+}

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

@@ -0,0 +1,59 @@
+import type { ModuleStoragePort } from "@southwind-ai/server-sdk";
+import {
+  UploadError,
+  type FileService,
+  type UploadService,
+} from "@southwind-ai/storage";
+
+export interface ModuleStorageServices {
+  uploads: UploadService;
+  files: FileService;
+}
+
+export interface ModuleStorageScope {
+  moduleName: string;
+  ownerId: string;
+  /** 本模块经 Host 注册的上传用途集合；跨模块与平台用途一律拒绝。 */
+  purposes: ReadonlySet<string>;
+}
+
+/**
+ * 模块受限 Upload / BlobRead Port。
+ *
+ * - 上传会话强制 purpose ∈ 本模块已注册 Policy，Owner 由宿主以当前 Actor 补齐；
+ * - 文件读取走 FileService 的 Owner 约束，且文件用途必须属于本模块；
+ * - 公开读取走 FileService 的 Purpose 约束，用途同样必须属于本模块；
+ * - 模块不直接接触 BlobStore 或 Upload Repository。
+ */
+export function createModuleStoragePort(
+  services: ModuleStorageServices,
+  scope: ModuleStorageScope,
+): ModuleStoragePort {
+  return {
+    async createUploadSession(input) {
+      requireModulePurpose(scope, input.purpose);
+      return services.uploads.create({ ...input, ownerId: scope.ownerId });
+    },
+    async openFile(fileId) {
+      const file = await services.files.open(fileId, scope.ownerId);
+      requireModulePurpose(scope, file.purpose);
+      return file;
+    },
+    async openPublicFile(fileId, purpose) {
+      requireModulePurpose(scope, purpose);
+      return services.files.openPublic(fileId, purpose);
+    },
+  };
+}
+
+function requireModulePurpose(
+  scope: ModuleStorageScope,
+  purpose: string,
+): void {
+  if (!scope.purposes.has(purpose)) {
+    throw new UploadError(
+      "UPLOAD_FORBIDDEN",
+      `上传用途不属于模块 ${scope.moduleName}：${purpose}`,
+    );
+  }
+}

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

@@ -0,0 +1,41 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { ScheduledTaskDefinition } from "../scheduler/types.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+
+/**
+ * 把模块经 Host 注册的定时任务 Handler 与 Manifest 声明合并为调度定义。
+ * 调度元数据一律以 Manifest 为准；声明了任务但没注册 Handler 的模块
+ * 会在最终 Composition 校验时报错。
+ */
+export function createModuleTaskDefinitions(
+  hosts: InitializedModuleHosts,
+  features: readonly FeatureFlagDefinition[],
+): ScheduledTaskDefinition[] {
+  const handlerByKey = new Map(
+    hosts.taskHandlers.map(
+      ({ registration }) => [registration.taskKey, registration] as const,
+    ),
+  );
+  return hosts.manifests.flatMap((manifest) =>
+    manifest.tasks.flatMap((task) => {
+      const registration = handlerByKey.get(task.key);
+      if (!registration) return [];
+      const feature = features.find(({ key }) => key === task.featureKey);
+      if (!feature) throw new Error(`缺少 ${task.featureKey} Feature 定义`);
+      return [
+        {
+          key: task.key,
+          label: task.label,
+          description: task.description,
+          intervalSeconds: task.intervalSeconds,
+          maxAttempts: task.maxAttempts,
+          retryDelaySeconds: task.retryDelaySeconds,
+          permissionKey: task.permissionKey,
+          feature,
+          handler: registration.handler,
+          isIdleResult: registration.isIdleResult,
+        },
+      ];
+    }),
+  );
+}

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

@@ -0,0 +1,26 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+
+/** 模块 Host 测试共用的最小 Manifest 夹具。 */
+export 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,
+  };
+}

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

@@ -0,0 +1,25 @@
+import type { ModuleToolHandlers } from "../agent/routes.js";
+import type { InitializedModuleHosts } from "./initialize.js";
+import { toModuleActor } from "./request-context.js";
+
+/**
+ * 把模块经 Host 注册的 Agent Tool Handler 适配为 Agent 路由层的
+ * Handler Map；注册与 Manifest 声明的一致性由 validateToolHandlerContract 校验。
+ */
+export function createModuleToolHandlerMap(
+  hosts: InitializedModuleHosts,
+): ModuleToolHandlers {
+  return new Map(
+    hosts.toolHandlers.map(({ registration }) => [
+      registration.toolKey,
+      {
+        scopeMode: registration.scopeMode,
+        execute: (query, context) =>
+          registration.execute(query, {
+            actor: toModuleActor(context.actor),
+            requestId: context.requestId,
+          }),
+      },
+    ]),
+  );
+}

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,
   };
 }