create-windy 0.3.18 → 0.4.0

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

@@ -10,6 +10,7 @@ import type {
   InitializedModuleHosts,
   InitializeModuleHostsInput,
   RegisteredModuleAiOperationHandler,
+  RegisteredModuleDurableHandler,
   RegisteredModuleGovernedResource,
   RegisteredModuleRolePreset,
   RegisteredModuleRoute,
@@ -26,11 +27,13 @@ import {
 } from "./resource-file-policies.js";
 import { validateRouteDeclaration } from "./route-declaration.js";
 import { createScopedSandboxHost } from "./sandbox-tool-registration.js";
+import { validateSearchProviderRegistration } from "./search-provider-registration.js";
 
 export type {
   InitializedModuleHosts,
   InitializeModuleHostsInput,
   RegisteredModuleAiOperationHandler,
+  RegisteredModuleDurableHandler,
   RegisteredModuleGovernedResource,
   RegisteredModuleRolePreset,
   RegisteredModuleRoute,
@@ -73,6 +76,7 @@ export async function initializeModuleHosts(
     resourceFileAccessPolicyKeys: new Set<string>(),
     handlerKeys: new Set<string>(),
     handlerInstallers: [],
+    durableHandlers: [],
     routes: [],
     routeKeys: new Set<string>(),
     taskHandlers: [],
@@ -141,6 +145,7 @@ export async function initializeModuleHosts(
     toolHandlers: [...state.toolHandlers],
     sandboxToolHandlers: [...state.sandboxToolHandlers],
     aiOperationHandlers: [...state.aiOperationHandlers],
+    durableHandlers: [...state.durableHandlers],
     governedResources: [...state.governedResources],
     rolePresets: [...state.rolePresets],
     searchProviders: [...state.searchProviders],
@@ -155,6 +160,13 @@ export async function initializeModuleHosts(
     resourceFileAccessPoliciesOf(moduleName) {
       return state.moduleResourceFileAccessPolicies.get(moduleName) ?? [];
     },
+    durableHandlerOf(moduleName, handlerKey) {
+      return state.durableHandlers.find(
+        (entry) =>
+          entry.moduleName === moduleName &&
+          entry.definition.key === handlerKey,
+      )?.definition;
+    },
     installDurableHandlers(registry) {
       for (const install of state.handlerInstallers) install(registry);
     },
@@ -174,6 +186,7 @@ interface HostCollections {
   resourceFileAccessPolicyKeys: Set<string>;
   handlerKeys: Set<string>;
   handlerInstallers: HandlerInstaller[];
+  durableHandlers: RegisteredModuleDurableHandler[];
   routes: RegisteredModuleRoute[];
   routeKeys: Set<string>;
   taskHandlers: RegisteredModuleTaskHandler[];
@@ -215,7 +228,7 @@ function createScopedHost(
     },
     registerDurableHandler(definition) {
       requireModuleNamespace("任务 handler", definition.key, moduleName);
-      registerModuleDurableHandler(moduleName, state, definition);
+      registerModuleDurableHandler(manifest, state, definition);
     },
     registerGovernedResources(registrations) {
       registerGovernedResources(manifest, state, registrations);
@@ -323,9 +336,7 @@ function createScopedHost(
     registerSearchProviders(providers) {
       for (const provider of providers) {
         requireModuleNamespace("搜索 Provider", provider.key, moduleName);
-        if (!manifest.providers.some(({ key }) => key === provider.key)) {
-          throw new Error(`搜索 Provider 未在 Manifest 声明：${provider.key}`);
-        }
+        validateSearchProviderRegistration(manifest, provider);
         if (state.searchProviderKeys.has(provider.key)) {
           throw new Error(`搜索 Provider 重复注册：${provider.key}`);
         }

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

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import { attachProjectServerModules } from "./project-attachments.js";
+
+describe("project-owned Server Module attachment", () => {
+  test("只挂载已启用且有本地 Adapter 的显式 attachment", async () => {
+    const attached: string[] = [];
+    await attachProjectServerModules({
+      attachments: [
+        {
+          name: "enabled",
+          attach: () => {
+            attached.push("enabled");
+          },
+        },
+        {
+          name: "disabled",
+          attach: () => {
+            attached.push("disabled");
+          },
+        },
+      ],
+      adapters: [
+        adapter("enabled", "project-attachment"),
+        adapter("disabled", "project-attachment"),
+      ],
+      enabledModuleNames: new Set(["enabled"]),
+      runtime: {},
+    });
+
+    expect(attached).toEqual(["enabled"]);
+  });
+
+  test("重复或没有本地 Adapter 的 attachment fail closed", async () => {
+    await expect(
+      attachProjectServerModules({
+        attachments: [
+          { name: "case", attach() {} },
+          { name: "case", attach() {} },
+        ],
+        adapters: [adapter("case", "project-attachment")],
+        enabledModuleNames: new Set(["case"]),
+        runtime: {},
+      }),
+    ).rejects.toThrow("attachment 重复：case");
+
+    await expect(
+      attachProjectServerModules({
+        attachments: [{ name: "package-only", attach() {} }],
+        adapters: [],
+        enabledModuleNames: new Set(["package-only"]),
+        runtime: {},
+      }),
+    ).rejects.toThrow("attachment 缺少本地 Adapter：package-only");
+  });
+
+  test("先完整预检再执行，且启用的 project-attachment 不能缺失", async () => {
+    const effects: string[] = [];
+    await expect(
+      attachProjectServerModules({
+        attachments: [
+          { name: "case", attach: () => void effects.push("first") },
+          { name: "case", attach: () => void effects.push("duplicate") },
+        ],
+        adapters: [adapter("case", "project-attachment")],
+        enabledModuleNames: new Set(["case"]),
+        runtime: {},
+      }),
+    ).rejects.toThrow("attachment 重复：case");
+    expect(effects).toEqual([]);
+
+    await expect(
+      attachProjectServerModules({
+        attachments: [],
+        adapters: [adapter("case", "project-attachment")],
+        enabledModuleNames: new Set(["case"]),
+        runtime: {},
+      }),
+    ).rejects.toThrow("缺少 runtime attachment：case");
+  });
+});
+
+function adapter(
+  name: string,
+  runtimeMode: "self-contained" | "project-attachment",
+) {
+  return {
+    name,
+    hostRange: "^0.1.0",
+    runtimeMode,
+    create: () => ({ manifest: {}, setup() {} }),
+  };
+}

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

@@ -0,0 +1,58 @@
+import type {
+  WindyServerModuleAdapter,
+  WindyServerModuleAttachment,
+} from "@southwind-ai/server-sdk";
+
+export async function attachProjectServerModules<TRuntime>(input: {
+  readonly attachments: readonly WindyServerModuleAttachment<TRuntime>[];
+  readonly adapters: readonly WindyServerModuleAdapter<unknown>[];
+  readonly enabledModuleNames: ReadonlySet<string>;
+  readonly runtime: TRuntime;
+}): Promise<void> {
+  const active = validateProjectServerAttachments(input);
+  for (const attachment of active) {
+    await attachment.attach(input.runtime);
+  }
+}
+
+export function validateProjectServerAttachments<TRuntime>(input: {
+  readonly attachments: readonly WindyServerModuleAttachment<TRuntime>[];
+  readonly adapters: readonly WindyServerModuleAdapter<unknown>[];
+  readonly enabledModuleNames: ReadonlySet<string>;
+}): readonly WindyServerModuleAttachment<TRuntime>[] {
+  const adapters = new Map(
+    input.adapters.map((adapter) => [adapter.name, adapter]),
+  );
+  const seen = new Set<string>();
+  for (const attachment of input.attachments) {
+    if (seen.has(attachment.name)) {
+      throw new Error(`项目 Server Module attachment 重复：${attachment.name}`);
+    }
+    seen.add(attachment.name);
+    const adapter = adapters.get(attachment.name);
+    if (!adapter) {
+      throw new Error(
+        `项目 Server Module attachment 缺少本地 Adapter：${attachment.name}`,
+      );
+    }
+    if (adapter.runtimeMode !== "project-attachment") {
+      throw new Error(
+        `项目 Server Module attachment 不能挂载 self-contained Adapter：${attachment.name}`,
+      );
+    }
+  }
+  for (const adapter of input.adapters) {
+    if (
+      adapter.runtimeMode === "project-attachment" &&
+      input.enabledModuleNames.has(adapter.name) &&
+      !seen.has(adapter.name)
+    ) {
+      throw new Error(
+        `项目 Server Module 缺少 runtime attachment：${adapter.name}`,
+      );
+    }
+  }
+  return input.attachments.filter(({ name }) =>
+    input.enabledModuleNames.has(name),
+  );
+}

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

@@ -0,0 +1,186 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+import {
+  SERVER_MODULE_HOST_VERSION,
+  resolveProjectServerComposition,
+} from "./project-composition.js";
+
+describe("package Server Module 标准导出", () => {
+  test("从 package 根加载 Adapter，从 ./manifest 加载唯一 Manifest", async () => {
+    const exports = packageExports("case", `^${SERVER_MODULE_HOST_VERSION}`);
+    const composition = await resolveProjectServerComposition({
+      assembly: assembly(),
+      adapters: [],
+      platformModules: platformModules(),
+      importPackage: packageImporter(exports),
+    });
+
+    expect(composition.modules[0]?.manifest).toBe(exports.windyModuleManifest);
+  });
+
+  test("Host range、标准导出与 Manifest 身份漂移时 fail closed", async () => {
+    const incompatible = packageExports("case", "^9.0.0");
+    await expect(resolve(incompatible)).rejects.toThrow(
+      "要求 Server Host ^9.0.0",
+    );
+
+    const valid = packageExports("case", "^0.1.0");
+    await expect(
+      resolveProjectServerComposition({
+        assembly: assembly(),
+        adapters: [],
+        platformModules: platformModules(),
+        importPackage: async (specifier) =>
+          specifier.endsWith("/manifest")
+            ? { windyModuleManifest: valid.windyModuleManifest }
+            : {},
+      }),
+    ).rejects.toThrow("缺少 windyServerModule 标准导出");
+
+    await expect(
+      resolve({
+        ...valid,
+        windyServerModule: {
+          ...valid.windyServerModule,
+          create: () => installable("other"),
+        },
+      }),
+    ).rejects.toThrow("返回了错误 Manifest：other");
+
+    await expect(
+      resolveProjectServerComposition({
+        assembly: assembly(),
+        adapters: [],
+        platformModules: platformModules(),
+        importPackage: async (specifier) =>
+          specifier.endsWith("/manifest") ? {} : valid,
+      }),
+    ).rejects.toThrow("缺少 ./manifest windyModuleManifest 标准导出");
+
+    await expect(
+      resolve({
+        ...valid,
+        windyServerModule: {
+          ...valid.windyServerModule,
+          create: () => installable("case"),
+        },
+      }),
+    ).rejects.toThrow("未使用 windyModuleManifest 同一声明");
+
+    await expect(
+      resolveProjectServerComposition({
+        assembly: assembly(),
+        adapters: [],
+        platformModules: platformModules(),
+        importPackage: async (specifier) =>
+          specifier.endsWith("/manifest")
+            ? { windyModuleManifest: installable("case").manifest }
+            : valid,
+      }),
+    ).rejects.toThrow("根导出与 ./manifest 不一致");
+  });
+
+  test("本地 Adapter 仍必须复用 package ./manifest", async () => {
+    const canonical = installable("case");
+    await expect(
+      resolveProjectServerComposition({
+        assembly: assembly(),
+        adapters: [
+          {
+            name: "case",
+            hostRange: "^0.1.0",
+            runtimeMode: "project-attachment",
+            create: () => installable("case"),
+          },
+        ],
+        platformModules: platformModules(),
+        importPackage: async (specifier) => {
+          expect(specifier).toBe("@customer/case/manifest");
+          return { windyModuleManifest: canonical.manifest };
+        },
+      }),
+    ).rejects.toThrow("未使用 windyModuleManifest 同一声明");
+  });
+});
+
+function resolve(exports: ReturnType<typeof packageExports>) {
+  return resolveProjectServerComposition({
+    assembly: assembly(),
+    adapters: [],
+    platformModules: platformModules(),
+    importPackage: packageImporter(exports),
+  });
+}
+
+function packageImporter(exports: ReturnType<typeof packageExports>) {
+  return async (specifier: string) =>
+    specifier.endsWith("/manifest")
+      ? { windyModuleManifest: exports.windyModuleManifest }
+      : exports;
+}
+
+function packageExports(name: string, hostRange: string) {
+  const module = installable(name);
+  return {
+    windyModuleManifest: module.manifest,
+    windyServerModule: {
+      name,
+      hostRange,
+      runtimeMode: "self-contained" as const,
+      create: () => module,
+    },
+  };
+}
+
+function assembly() {
+  return {
+    schemaVersion: 1 as const,
+    modules: [
+      registration("system", null, 10),
+      registration("system.identity", null, 20),
+      registration("case", "@customer/case", 100),
+    ],
+  };
+}
+
+function registration(name: string, packageName: string | null, order: number) {
+  return {
+    name,
+    package: packageName,
+    enabled: true,
+    order,
+    admin: { visible: true },
+    config: {},
+  };
+}
+
+function platformModules(): readonly ModuleManifest[] {
+  return [
+    installable("system").manifest,
+    installable("system.identity").manifest,
+  ];
+}
+
+function installable(name: string): InstallableServerModule<ModuleManifest> {
+  return {
+    manifest: {
+      name,
+      version: "1.0.0",
+      label: name,
+      description: `${name} module`,
+      menus: [],
+      adminRoutes: [],
+      permissions: [],
+      apiPermissions: [],
+      features: [],
+      migrations: [],
+      schemaExports: [],
+      tasks: [],
+      tools: [],
+      providers: [],
+      auditActions: [],
+    },
+    setup() {},
+  };
+}

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

@@ -0,0 +1,260 @@
+import { describe, expect, test } from "bun:test";
+import {
+  // @windy-module system.data-governance begin
+  systemModuleManifests,
+  // @windy-module system.data-governance end
+  type ModuleManifest,
+} from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+import { resolveProjectServerComposition } from "./project-composition.js";
+
+describe("project-owned Server Composition", () => {
+  test("按装配清单启用状态与顺序加载项目 Adapter", async () => {
+    const adapters = [adapter("disabled"), adapter("second"), adapter("first")];
+    const composition = await resolveProjectServerComposition({
+      assembly: assembly([
+        registration("disabled", false, 100),
+        registration("second", true, 300),
+        registration("first", true, 200),
+      ]),
+      adapters,
+      platformModules: platformModules(),
+      importPackage: localManifestImporter(adapters),
+    });
+
+    expect(composition.modules.map(({ manifest }) => manifest.name)).toEqual([
+      "first",
+      "second",
+    ]);
+  });
+
+  test("平台 Module 与 package 注册必须双向一致", async () => {
+    await expect(
+      resolveProjectServerComposition({
+        assembly: assembly([]),
+        adapters: [],
+        platformModules: platformModules(
+          "system",
+          "system.identity",
+          "system.audit",
+        ),
+        importPackage: unexpectedImport,
+      }),
+    ).rejects.toThrow("平台 Module 未在 windy.modules.json 注册：system.audit");
+
+    await expect(
+      resolveProjectServerComposition({
+        assembly: {
+          ...assembly([]),
+          modules: [
+            ...assembly([]).modules,
+            {
+              name: "ghost",
+              package: null,
+              enabled: true,
+              order: 500,
+              admin: { visible: true },
+              config: {},
+            },
+          ],
+        },
+        adapters: [],
+        platformModules: platformModules(),
+        importPackage: unexpectedImport,
+      }),
+    ).rejects.toThrow("引用了未知平台 Module：ghost");
+
+    await expect(
+      resolveProjectServerComposition({
+        assembly: {
+          ...assembly([]),
+          modules: assembly([]).modules.map((module) =>
+            module.name === "system.identity"
+              ? { ...module, enabled: false }
+              : module,
+          ),
+        },
+        adapters: [],
+        platformModules: platformModules(),
+        importPackage: unexpectedImport,
+      }),
+    ).rejects.toThrow(
+      "windy.modules.json 必须启用平台 Module：system.identity",
+    );
+  });
+
+  // @windy-module system.data-governance begin
+  test("跨模块 Feature 贡献不能声明为运行时停用", async () => {
+    const platform = systemModuleManifests().filter(({ name }) =>
+      ["system", "system.identity", "system.data-governance"].includes(name),
+    );
+    await expect(
+      resolveProjectServerComposition({
+        assembly: {
+          ...assembly([]),
+          modules: [
+            ...assembly([]).modules,
+            {
+              name: "system.data-governance",
+              package: null,
+              enabled: false,
+              order: 500,
+              admin: { visible: true },
+              config: {},
+            },
+          ],
+        },
+        adapters: [],
+        platformModules: platform,
+        importPackage: unexpectedImport,
+      }),
+    ).rejects.toThrow(
+      "平台 Module 不能仅通过运行时停用：system.data-governance",
+    );
+  });
+  // @windy-module system.data-governance end
+
+  test("启用模块的 Manifest 依赖必须同时启用", async () => {
+    const caseModule = installable("case");
+    caseModule.manifest.dependencies = ["system.scheduler"];
+    const caseAdapter = {
+      ...adapter("case"),
+      create: () => caseModule,
+    };
+    await expect(
+      resolveProjectServerComposition({
+        assembly: {
+          ...assembly([registration("case", true, 600)]),
+          modules: [
+            ...assembly([]).modules,
+            {
+              name: "system.scheduler",
+              package: null,
+              enabled: false,
+              order: 500,
+              admin: { visible: true },
+              config: {},
+            },
+            registration("case", true, 600),
+          ],
+        },
+        adapters: [caseAdapter],
+        platformModules: platformModules(
+          "system",
+          "system.identity",
+          "system.scheduler",
+        ),
+        importPackage: localManifestImporter([caseAdapter]),
+      }),
+    ).rejects.toThrow("Module case 依赖未启用 Module：system.scheduler");
+  });
+
+  test("装配清单拒绝重复 order、负数 order 和非法 package", async () => {
+    for (const modules of [
+      [registration("first", true, 100), registration("second", true, 100)],
+      [registration("negative", true, -1)],
+      [{ ...registration("bad", true, 100), package: "../bad" }],
+      [{ ...registration("uppercase", true, 100), package: "@Customer/case" }],
+    ]) {
+      await expect(
+        resolveProjectServerComposition({
+          assembly: assembly(modules),
+          adapters: [],
+          platformModules: platformModules(),
+          importPackage: unexpectedImport,
+        }),
+      ).rejects.toThrow("windy.modules.json");
+    }
+  });
+});
+
+function assembly(modules: Array<ReturnType<typeof registration>>) {
+  return {
+    schemaVersion: 1 as const,
+    modules: [
+      {
+        name: "system",
+        package: null,
+        enabled: true,
+        order: 10,
+        admin: { visible: true },
+        config: {},
+      },
+      {
+        name: "system.identity",
+        package: null,
+        enabled: true,
+        order: 20,
+        admin: { visible: true },
+        config: {},
+      },
+      ...modules,
+    ],
+  };
+}
+
+function registration(name: string, enabled: boolean, order: number) {
+  return {
+    name,
+    package: `@customer/${name}`,
+    enabled,
+    order,
+    admin: { visible: true },
+    config: {},
+  };
+}
+
+function adapter(name: string) {
+  const module = installable(name);
+  return {
+    name,
+    hostRange: "^0.1.0",
+    runtimeMode: "project-attachment" as const,
+    create: () => module,
+  };
+}
+
+function localManifestImporter(
+  adapters: readonly ReturnType<typeof adapter>[],
+) {
+  return async (specifier: string) => {
+    const adapter = adapters.find(({ name }) =>
+      specifier.endsWith(`/${name}/manifest`),
+    );
+    if (!adapter) throw new Error(`未找到测试 Adapter：${specifier}`);
+    return { windyModuleManifest: (await adapter.create()).manifest };
+  };
+}
+
+function installable(name: string): InstallableServerModule<ModuleManifest> {
+  return {
+    manifest: {
+      name,
+      version: "1.0.0",
+      label: name,
+      description: `${name} module`,
+      menus: [],
+      adminRoutes: [],
+      permissions: [],
+      apiPermissions: [],
+      features: [],
+      migrations: [],
+      schemaExports: [],
+      tasks: [],
+      tools: [],
+      providers: [],
+      auditActions: [],
+    },
+    setup() {},
+  };
+}
+
+async function unexpectedImport(): Promise<never> {
+  throw new Error("不应加载 package");
+}
+
+function platformModules(...names: string[]): readonly ModuleManifest[] {
+  return (names.length ? names : ["system", "system.identity"])
+    .map(installable)
+    .map(({ manifest }) => manifest);
+}