create-windy 0.3.19 → 0.4.0

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);
+}