create-windy 0.3.19 → 0.4.1

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

@@ -0,0 +1,311 @@
+import {
+  indexProjectModuleAssembly,
+  satisfiesModuleHostRange,
+  validateProjectModuleAssembly,
+  type ModuleManifest,
+  type ProjectModuleRegistration,
+} from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  WindyServerModuleAdapter,
+} from "@southwind-ai/server-sdk";
+
+export const SERVER_MODULE_HOST_VERSION = "0.1.0";
+
+export type {
+  ProjectModuleAssembly,
+  ProjectModuleRegistration,
+} from "@southwind-ai/modules";
+
+export type ProjectServerModule = WindyServerModuleAdapter<ModuleManifest>;
+
+export interface ProjectServerComposition {
+  readonly modules: readonly InstallableServerModule<ModuleManifest>[];
+  readonly enabledModuleNames: ReadonlySet<string>;
+}
+
+interface ResolveProjectServerCompositionInput {
+  readonly assembly: unknown;
+  readonly adapters: readonly ProjectServerModule[];
+  readonly platformModules: readonly ModuleManifest[];
+  readonly importPackage?: (packageName: string) => Promise<unknown>;
+  readonly hostVersion?: string;
+}
+
+export async function resolveProjectServerComposition(
+  input: ResolveProjectServerCompositionInput,
+): Promise<ProjectServerComposition> {
+  const registrations = indexProjectModuleAssembly(
+    validateProjectModuleAssembly(input.assembly),
+  );
+  validatePlatformAssembly(registrations, input.platformModules);
+  const adapters = validateAdapters(input.adapters, registrations);
+  const hostVersion = input.hostVersion ?? SERVER_MODULE_HOST_VERSION;
+  const importPackage =
+    input.importPackage ?? ((packageName: string) => import(packageName));
+
+  const enabled = [...registrations.values()]
+    .filter(({ enabled }) => enabled)
+    .sort(
+      (left, right) =>
+        left.order - right.order || left.name.localeCompare(right.name),
+    );
+  const modules: InstallableServerModule<ModuleManifest>[] = [];
+
+  for (const registration of enabled) {
+    if (registration.package === null) continue;
+    const localAdapter = adapters.get(registration.name);
+    const canonicalManifest = await loadPackageManifest(
+      registration,
+      importPackage,
+    );
+    const adapter =
+      localAdapter ??
+      (await loadPackageAdapter(
+        registration,
+        canonicalManifest,
+        importPackage,
+      ));
+    assertHostCompatible(adapter, hostVersion);
+    const module = await adapter.create(registration.config);
+    assertInstallableModule(registration.name, module, canonicalManifest);
+    modules.push(module);
+  }
+  validateEnabledDependencies(
+    registrations,
+    input.platformModules,
+    modules.map(({ manifest }) => manifest),
+  );
+
+  return {
+    modules,
+    enabledModuleNames: new Set(enabled.map(({ name }) => name)),
+  };
+}
+
+function validateEnabledDependencies(
+  registrations: ReadonlyMap<string, ProjectModuleRegistration>,
+  platformModules: readonly ModuleManifest[],
+  businessModules: readonly ModuleManifest[],
+): void {
+  const enabledNames = new Set(
+    [...registrations.values()]
+      .filter(({ enabled }) => enabled)
+      .map(({ name }) => name),
+  );
+  const manifests = new Map(
+    [...platformModules, ...businessModules].map((manifest) => [
+      manifest.name,
+      manifest,
+    ]),
+  );
+  for (const name of enabledNames) {
+    const manifest = manifests.get(name);
+    if (!manifest) throw new Error(`启用的 Module 缺少 Manifest：${name}`);
+    for (const dependency of manifest.dependencies ?? []) {
+      if (!enabledNames.has(dependency)) {
+        throw new Error(`Module ${name} 依赖未启用 Module：${dependency}`);
+      }
+    }
+  }
+}
+
+function validatePlatformAssembly(
+  registrations: ReadonlyMap<string, ProjectModuleRegistration>,
+  platformModules: readonly ModuleManifest[],
+): void {
+  const platformNames = new Set(platformModules.map(({ name }) => name));
+  for (const name of platformNames) {
+    const registration = registrations.get(name);
+    if (!registration) {
+      throw new Error(`平台 Module 未在 windy.modules.json 注册：${name}`);
+    }
+    if (registration.package !== null) {
+      throw new Error(
+        `平台 Module 在 windy.modules.json 中必须使用 package=null：${name}`,
+      );
+    }
+  }
+  for (const registration of registrations.values()) {
+    if (
+      registration.package === null &&
+      !platformNames.has(registration.name)
+    ) {
+      throw new Error(
+        `windy.modules.json 引用了未知平台 Module：${registration.name}`,
+      );
+    }
+  }
+  for (const required of ["system", "system.identity"]) {
+    const registration = registrations.get(required);
+    if (!registration?.enabled || registration.package !== null) {
+      throw new Error(`windy.modules.json 必须启用平台 Module：${required}`);
+    }
+  }
+  for (const manifest of platformModules) {
+    if (!registrations.get(manifest.name)?.enabled) {
+      assertRuntimeDisableSafe(manifest);
+    }
+  }
+}
+
+function assertRuntimeDisableSafe(manifest: ModuleManifest): void {
+  if (manifest.metadata?.runtimeActivation === "physical-only") {
+    throw new Error(
+      `平台 Module 不能仅通过运行时停用：${manifest.name}；请在生成或升级阶段物理移除`,
+    );
+  }
+  const ownedFeatures = new Set<string>(
+    manifest.features.map(({ key }) => key),
+  );
+  const guardedFeatureKeys = [
+    ...manifest.adminRoutes.map(({ featureKey }) => featureKey),
+    ...manifest.apiPermissions.map(({ featureKey }) => featureKey),
+    ...manifest.tasks.map(({ featureKey }) => featureKey),
+    ...manifest.tools.map(({ featureKey }) => featureKey),
+    ...(manifest.aiOperations ?? []).map(({ featureKey }) => featureKey),
+    ...manifest.providers.map(({ featureKey }) => featureKey),
+    ...(manifest.dataPolicies ?? []).map(({ featureKey }) => featureKey),
+  ].filter((key): key is string => Boolean(key));
+  if (guardedFeatureKeys.some((key) => !ownedFeatures.has(key))) {
+    throw new Error(
+      `平台 Module 不能仅通过运行时停用：${manifest.name}；请在生成或升级阶段物理移除`,
+    );
+  }
+}
+
+function validateAdapters(
+  definitions: readonly ProjectServerModule[],
+  registrations: ReadonlyMap<string, ProjectModuleRegistration>,
+): ReadonlyMap<string, ProjectServerModule> {
+  const adapters = new Map<string, ProjectServerModule>();
+  for (const definition of definitions) {
+    if (!registrations.has(definition.name)) {
+      throw new Error(
+        `Server Adapter 未在 windy.modules.json 注册：${definition.name}`,
+      );
+    }
+    if (adapters.has(definition.name)) {
+      throw new Error(`Server Adapter 重复：${definition.name}`);
+    }
+    if (registrations.get(definition.name)?.package === null) {
+      throw new Error(
+        `平台 Module 不能注册 Server Adapter：${definition.name}`,
+      );
+    }
+    adapters.set(definition.name, definition);
+  }
+  return adapters;
+}
+
+async function loadPackageAdapter(
+  registration: ProjectModuleRegistration,
+  canonicalManifest: ModuleManifest,
+  importPackage: (packageName: string) => Promise<unknown>,
+): Promise<ProjectServerModule> {
+  const packageName = registration.package!;
+  const loaded = await importPackage(packageName);
+  if (!isRecord(loaded) || !isProjectServerModule(loaded.windyServerModule)) {
+    throw new Error(
+      `Module ${registration.name} 缺少 windyServerModule 标准导出`,
+    );
+  }
+  if (loaded.windyServerModule.name !== registration.name) {
+    throw new Error(
+      `Module package ${registration.package} 导出了错误 Adapter：${loaded.windyServerModule.name}`,
+    );
+  }
+  if (loaded.windyServerModule.runtimeMode !== "self-contained") {
+    throw new Error(
+      `动态 Module ${registration.name} 不能要求项目 runtime attachment`,
+    );
+  }
+  if (
+    isModuleManifest(loaded.windyModuleManifest) &&
+    loaded.windyModuleManifest !== canonicalManifest
+  ) {
+    throw new Error(`Module ${registration.name} 根导出与 ./manifest 不一致`);
+  }
+  return loaded.windyServerModule;
+}
+
+async function loadPackageManifest(
+  registration: ProjectModuleRegistration,
+  importPackage: (packageName: string) => Promise<unknown>,
+): Promise<ModuleManifest> {
+  const packageName = registration.package!;
+  const loaded = await importPackage(`${packageName}/manifest`);
+  if (!isRecord(loaded) || !isModuleManifest(loaded.windyModuleManifest)) {
+    throw new Error(
+      `Module ${registration.name} 缺少 ./manifest windyModuleManifest 标准导出`,
+    );
+  }
+  if (loaded.windyModuleManifest.name !== registration.name) {
+    throw new Error(
+      `Module package ${packageName} 导出了错误 Manifest：${loaded.windyModuleManifest.name}`,
+    );
+  }
+  return loaded.windyModuleManifest;
+}
+
+function isProjectServerModule(value: unknown): value is ProjectServerModule {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.hostRange === "string" &&
+    (value.runtimeMode === "self-contained" ||
+      value.runtimeMode === "project-attachment") &&
+    typeof value.create === "function"
+  );
+}
+
+function assertInstallableModule(
+  expectedName: string,
+  value: InstallableServerModule<ModuleManifest>,
+  packageManifest?: ModuleManifest,
+): void {
+  if (
+    !isRecord(value) ||
+    !isRecord(value.manifest) ||
+    typeof value.manifest.name !== "string" ||
+    typeof value.setup !== "function"
+  ) {
+    throw new Error(`Server Adapter ${expectedName} 返回了无效 Module`);
+  }
+  if (value.manifest.name !== expectedName) {
+    throw new Error(
+      `Server Adapter ${expectedName} 返回了错误 Manifest：${value.manifest.name}`,
+    );
+  }
+  if (packageManifest && value.manifest !== packageManifest) {
+    throw new Error(
+      `Server Adapter ${expectedName} 未使用 windyModuleManifest 同一声明`,
+    );
+  }
+}
+
+function assertHostCompatible(
+  adapter: ProjectServerModule,
+  hostVersion: string,
+): void {
+  if (!satisfiesModuleHostRange(hostVersion, adapter.hostRange)) {
+    throw new Error(
+      `Server Module ${adapter.name} 要求 Server Host ${adapter.hostRange}，当前为 ${hostVersion}`,
+    );
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isModuleManifest(value: unknown): value is ModuleManifest {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.version === "string" &&
+    Array.isArray(value.features) &&
+    Array.isArray(value.permissions) &&
+    Array.isArray(value.apiPermissions)
+  );
+}

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

@@ -91,6 +91,7 @@ export interface ModuleRequestContextInput {
   userDirectory?: ModuleUserDirectoryPort;
   aiArtifacts?: ModuleAiArtifactPort;
   aiOperations?: ModuleAiOperationPort;
+  onAuditEmit?: (action: string) => void;
 }
 
 export function buildModuleRequestContext(
@@ -184,9 +185,11 @@ function createModuleAuditEmitter(
       const auditEvent = buildAuditEvent(input.guardContext, action, event);
       if (event.critical) {
         await input.runtime.auditSink.recordCriticalEvent(auditEvent);
+        input.onAuditEmit?.(action);
         return;
       }
       input.runtime.auditSink.recordEvent(auditEvent);
+      input.onAuditEmit?.(action);
     },
   };
 }

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

@@ -30,16 +30,25 @@ export function validateRouteDeclaration(
       `模块路由 Feature 未在 Manifest 注册：${binding.featureKey}`,
     );
   }
+  if (binding.anonymous !== true && !binding.auditAction) {
+    throw new Error(`模块路由缺少 Manifest 审计动作：${route}`);
+  }
+  if (
+    definition.auditAction !== undefined &&
+    definition.auditAction !== binding.auditAction
+  ) {
+    throw new Error(
+      `模块路由审计动作与 Manifest 声明不一致：${route}`,
+    );
+  }
   if (
-    definition.auditAction &&
+    binding.auditAction &&
     !manifest.auditActions.some((action) =>
       typeof action === "string"
-        ? action === definition.auditAction
-        : action.key === definition.auditAction,
+        ? action === binding.auditAction
+        : action.key === binding.auditAction,
     )
   ) {
-    throw new Error(
-      `模块路由审计动作未在 Manifest 注册：${definition.auditAction}`,
-    );
+    throw new Error(`模块路由审计动作未在 Manifest 注册：${binding.auditAction}`);
   }
 }

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

@@ -62,6 +62,18 @@ describe("模块 Guarded Route 安装", () => {
     );
   });
 
+  test("实现未重复声明动作时仍从 Manifest 自动审计读取 API", async () => {
+    const fixture = await createFixture();
+
+    await fixture.invoke("GET", "/shop/items");
+
+    expect(
+      fixture.runtime.auditSink
+        .list()
+        .filter(({ action }) => action === "data.read"),
+    ).toHaveLength(1);
+  });
+
   test("Handler 只能获得受限上下文：审计白名单、Jobs 命名空间与未挂载存储", async () => {
     const fixture = await createFixture({ withJobs: true });
     await fixture.invoke("GET", "/shop/items");
@@ -172,7 +184,6 @@ async function createFixture(options: FixtureOptions = {}) {
           method: "POST",
           path: "/api/shop/items",
           permissionKey: "shop.item.manage",
-          auditAction: "crud.create",
           handler: () => {
             state.handled = true;
             state.context = undefined;
@@ -286,12 +297,14 @@ function shopManifest(): ModuleManifest {
         path: "/api/shop/items",
         permissionKey: "shop.item.read",
         featureKey: "shop.feature",
+        auditAction: "data.read",
       },
       {
         method: "POST",
         path: "/api/shop/items",
         permissionKey: "shop.item.manage",
         featureKey: "shop.feature",
+        auditAction: "crud.create",
       },
     ],
     features: [
@@ -310,7 +323,7 @@ function shopManifest(): ModuleManifest {
     tasks: [],
     tools: [],
     providers: [],
-    auditActions: ["crud.create"],
+    auditActions: ["crud.create", "data.read"],
   };
 }
 

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

@@ -81,6 +81,7 @@ export function installModuleRoutes(
         { permission: binding, feature },
       );
       if (!decision.allowed) return forbidden(decision.reason);
+      const emittedAuditActions = new Set<string>();
       const requestContext = buildModuleRequestContext({
         moduleName,
         manifest,
@@ -133,10 +134,15 @@ export function installModuleRoutes(
               route.guardContext,
             )
           : undefined,
+        onAuditEmit: (action) => emittedAuditActions.add(action),
       });
       const result = await definition.handler(requestContext);
-      if (definition.auditAction) {
-        await requestContext.audit.emit(definition.auditAction, {
+      if (
+        binding.auditAction &&
+        isSuccessfulResult(result) &&
+        !emittedAuditActions.has(binding.auditAction)
+      ) {
+        await requestContext.audit.emit(binding.auditAction, {
           target: {
             type: "module-route",
             id: `${definition.method} ${definition.path}`,
@@ -148,6 +154,10 @@ export function installModuleRoutes(
   }
 }
 
+function isSuccessfulResult(value: unknown): boolean {
+  return !(value instanceof Response) || value.status < 400;
+}
+
 function stripApiPrefix(path: string): string {
   if (!path.startsWith("/api/")) {
     throw new Error(`模块路由路径必须以 /api 开头：${path}`);

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

@@ -17,6 +17,7 @@ describe("模块路由注册", () => {
           path: "/api/known/items",
           permissionKey: "known.item.read",
           featureKey: declaredFeature,
+          auditAction: "data.read",
         },
       ],
       features: [
@@ -29,6 +30,7 @@ describe("模块路由注册", () => {
           stage: "stable",
         },
       ],
+      auditActions: ["data.read"],
     });
 
     const initialized = await initializeModuleHosts({
@@ -50,6 +52,7 @@ describe("模块路由注册", () => {
           method: "GET",
           path: "/api/known/items",
           permissionKey: "known.item.read",
+          auditAction: "data.read",
         },
       ],
     });
@@ -78,9 +81,10 @@ describe("模块路由注册", () => {
             apiPermissions: [
               {
                 method: "GET",
-                path: "/api/known/items",
-                permissionKey: "known.item.read",
-                featureKey: featureKey("known.item"),
+          path: "/api/known/items",
+          permissionKey: "known.item.read",
+          featureKey: featureKey("known.item"),
+          auditAction: "data.read",
               },
             ],
           }),
@@ -105,6 +109,7 @@ describe("模块路由注册", () => {
           method: "GET",
           path: "/api/known/items",
           permissionKey: "known.item.manage",
+          auditAction: "data.read",
         },
       ],
     });
@@ -118,15 +123,19 @@ describe("模块路由注册", () => {
           method: "GET",
           path: "/api/known/items",
           permissionKey: "known.item.read",
+          auditAction: "data.read",
         },
       ],
+      auditActions: ["data.read"],
     });
     await expect(registerRoutes(readable, [route(), route()])).rejects.toThrow(
       "模块路由重复注册：GET /api/known/items",
     );
     await expect(
       registerRoutes(readable, [{ ...route(), auditAction: "crud.create" }]),
-    ).rejects.toThrow("模块路由审计动作未在 Manifest 注册：crud.create");
+    ).rejects.toThrow(
+      "模块路由审计动作与 Manifest 声明不一致：GET /api/known/items",
+    );
   });
 });
 

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

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+import { mergeLegacyAndProjectModules } from "./runtime-composition-compatibility.js";
+
+function module(name: string, version = "1.0.0") {
+  const manifest = {
+    name,
+    version,
+    label: name,
+    description: name,
+    dependencies: [],
+    features: [],
+    permissions: [],
+    menus: [],
+    adminRoutes: [],
+    apiPermissions: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+  } satisfies ModuleManifest;
+  return {
+    manifest,
+    setup() {},
+  } satisfies InstallableServerModule<ModuleManifest>;
+}
+
+describe("旧项目 Server 装配兼容", () => {
+  test("保留旧 project-owned 模块，并只把新增声明式模块交给新版 attachment", () => {
+    const legacyWorkOrder = module("work-order");
+    const declaredWorkOrder = module("work-order");
+    const declaredSearch = module("business.search");
+
+    const result = mergeLegacyAndProjectModules(
+      [legacyWorkOrder],
+      [declaredWorkOrder, declaredSearch],
+    );
+
+    expect(result.modules).toEqual([legacyWorkOrder, declaredSearch]);
+    expect([...result.projectOnlyModuleNames]).toEqual(["business.search"]);
+  });
+
+  test("同名旧模块与新版声明不兼容时 fail closed", () => {
+    expect(() =>
+      mergeLegacyAndProjectModules(
+        [module("work-order", "1.0.0")],
+        [module("work-order", "2.0.0")],
+      ),
+    ).toThrow("旧 Server Module 与声明式 Composition 不一致：work-order");
+  });
+
+  test("拒绝旧 project-owned 装配中的重复模块", () => {
+    expect(() =>
+      mergeLegacyAndProjectModules(
+        [module("work-order"), module("work-order")],
+        [],
+      ),
+    ).toThrow("旧 Server Module 重复：work-order");
+  });
+});

package/template/apps/server/src/module-host/runtime-composition-compatibility.ts

@@ -0,0 +1,46 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InstallableServerModule } from "@southwind-ai/server-sdk";
+
+export interface CompatibleRuntimeModules {
+  readonly modules: readonly InstallableServerModule<ModuleManifest>[];
+  readonly projectOnlyModuleNames: ReadonlySet<string>;
+}
+
+export function mergeLegacyAndProjectModules(
+  legacyModules: readonly InstallableServerModule<ModuleManifest>[],
+  projectModules: readonly InstallableServerModule<ModuleManifest>[],
+): CompatibleRuntimeModules {
+  const legacyByName = new Map<
+    string,
+    InstallableServerModule<ModuleManifest>
+  >();
+  for (const legacyModule of legacyModules) {
+    const name = legacyModule.manifest.name;
+    if (legacyByName.has(name)) {
+      throw new Error(`旧 Server Module 重复：${name}`);
+    }
+    legacyByName.set(name, legacyModule);
+  }
+
+  const modules = [...legacyModules];
+  const projectOnlyModuleNames = new Set<string>();
+  for (const projectModule of projectModules) {
+    const name = projectModule.manifest.name;
+    const legacyModule = legacyByName.get(name);
+    if (legacyModule) {
+      if (
+        JSON.stringify(legacyModule.manifest) !==
+        JSON.stringify(projectModule.manifest)
+      ) {
+        throw new Error(
+          `旧 Server Module 与声明式 Composition 不一致：${name}`,
+        );
+      }
+      continue;
+    }
+    modules.push(projectModule);
+    projectOnlyModuleNames.add(name);
+  }
+
+  return { modules, projectOnlyModuleNames };
+}

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

@@ -0,0 +1,34 @@
+import { systemModuleManifests } from "@southwind-ai/modules";
+import { serverCompositionDeclaration } from "../app/server-composition.js";
+import {
+  attachInstalledBusinessModules,
+  installedBusinessModules as legacyBusinessModules,
+} from "../installed-business-modules.js";
+import { attachProjectServerModules } from "./project-attachments.js";
+import { resolveProjectServerComposition } from "./project-composition.js";
+import { mergeLegacyAndProjectModules } from "./runtime-composition-compatibility.js";
+
+export const serverComposition = await resolveProjectServerComposition({
+  assembly: serverCompositionDeclaration.assembly,
+  adapters: serverCompositionDeclaration.adapters,
+  platformModules: systemModuleManifests(),
+});
+
+const compatibleModules = mergeLegacyAndProjectModules(
+  legacyBusinessModules,
+  serverComposition.modules,
+);
+
+export const runtimeBusinessModules = compatibleModules.modules;
+
+export async function attachRuntimeBusinessModules(
+  runtime: Parameters<typeof attachInstalledBusinessModules>[0],
+): Promise<void> {
+  await attachInstalledBusinessModules(runtime);
+  await attachProjectServerModules({
+    attachments: serverCompositionDeclaration.attachments ?? [],
+    adapters: serverCompositionDeclaration.adapters,
+    enabledModuleNames: compatibleModules.projectOnlyModuleNames,
+    runtime,
+  });
+}