create-windy 0.3.19 → 0.4.1

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

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleHost } from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import { initializeModuleHosts } from "./initialize.js";
+import {
+  governedResourceRouteKeys,
+  validateHostedModuleImplementations,
+} from "./implementation-completeness.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("Server Module 实现完整性", () => {
+  test("Manifest 声明的 API、任务和 Provider 必须由同一安装单元实现", async () => {
+    const complete = completeRouteModule();
+    const completeHosts = await initializeModuleHosts({
+      modules: [complete.manifest],
+      installations: [complete],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([complete], completeHosts),
+    ).not.toThrow();
+
+    const incomplete = {
+      manifest: complete.manifest,
+      setup() {},
+    };
+    const incompleteHosts = await initializeModuleHosts({
+      modules: [incomplete.manifest],
+      installations: [incomplete],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([incomplete], incompleteHosts),
+    ).toThrow("API Route GET /api/catalog/items 缺少 Handler");
+  });
+
+  test("治理资源注册派生读取、明文和四个导出 Handler Key", () => {
+    expect(
+      governedResourceRouteKeys({
+        readPath: "/api/people/persons/:id",
+        revealPath: "/api/people/persons/:id/plaintext",
+        export: {
+          basePath: "/api/people/persons/exports",
+          validateQuery: () => ({}),
+          readPage: () => ({ records: [] }),
+        },
+      }),
+    ).toEqual([
+      "GET /api/people/persons/:id",
+      "POST /api/people/persons/:id/plaintext",
+      "POST /api/people/persons/exports",
+      "GET /api/people/persons/exports/:id",
+      "POST /api/people/persons/exports/:id/cancel",
+      "GET /api/people/persons/exports/:id/download",
+    ]);
+  });
+
+  test("Durable Handler 的 Host 声明与 Registry 安装必须双向一致", async () => {
+    const capabilityKey = "reports.refresh";
+    const permissionKey = "reports.refresh.execute";
+    const moduleManifest = manifest("reports", {
+      features: [
+        {
+          key: featureKey(capabilityKey),
+          label: "报表刷新",
+          module: "reports",
+          visible: "visible",
+          enabled: true,
+          stage: "stable",
+        },
+      ],
+      permissions: [
+        {
+          key: permissionKey,
+          label: "执行报表刷新",
+          module: "reports",
+          moduleLabel: "报表",
+          resource: "refresh",
+          resourceLabel: "刷新",
+          action: "execute",
+        },
+      ],
+      tasks: [
+        {
+          key: capabilityKey,
+          label: "报表刷新",
+          description: "刷新报表。",
+          featureKey: capabilityKey,
+          permissionKey,
+          auditAction: permissionKey,
+          intervalSeconds: 60,
+          maxAttempts: 3,
+          retryDelaySeconds: 5,
+        },
+      ],
+      auditActions: [permissionKey],
+    });
+    const installation = {
+      manifest: moduleManifest,
+      setup(host: ModuleHost) {
+        moduleSetup(host);
+      },
+    };
+    const hosts = await initializeModuleHosts({
+      modules: [moduleManifest],
+      installations: [installation],
+    });
+
+    expect(() =>
+      validateHostedModuleImplementations([installation], hosts),
+    ).not.toThrow();
+    expect(() =>
+      validateHostedModuleImplementations([installation], {
+        ...hosts,
+        installDurableHandlers() {},
+      }),
+    ).toThrow("Durable Handler reports:reports.refresh 缺少 Handler");
+
+    function moduleSetup(host: ModuleHost) {
+      host.registerTaskHandlers([
+        { taskKey: capabilityKey, handler: () => undefined },
+      ]);
+      host.registerDurableHandler({
+        key: capabilityKey,
+        featureKey: capabilityKey,
+        permissionKey,
+        auditAction: permissionKey,
+        payload: { parse: () => ({}) },
+        execute: () => undefined,
+      });
+    }
+  });
+});
+
+function completeRouteModule() {
+  const capabilityKey = "catalog.item";
+  const permissionKey = "catalog.item.read";
+  const moduleManifest = manifest("catalog", {
+    features: [
+      {
+        key: featureKey(capabilityKey),
+        label: "目录项",
+        module: "catalog",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "查看目录",
+        module: "catalog",
+        moduleLabel: "目录",
+        resource: "item",
+        resourceLabel: "目录项",
+        action: "read",
+      },
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: "/api/catalog/items",
+        permissionKey,
+        featureKey: capabilityKey,
+        auditAction: "data.read",
+      },
+    ],
+    auditActions: ["data.read"],
+  });
+  return {
+    manifest: moduleManifest,
+    setup(host: ModuleHost) {
+      host.registerRoutes([
+        {
+          method: "GET",
+          path: "/api/catalog/items",
+          permissionKey,
+          featureKey: capabilityKey,
+          handler: () => ({ items: [] }),
+        },
+      ]);
+    },
+  };
+}

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

@@ -0,0 +1,132 @@
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleGovernedResourceRegistration,
+} from "@southwind-ai/server-sdk";
+import type { InitializedModuleHosts } from "./initialize-contracts.js";
+
+/**
+ * 校验经 Module Host 安装的业务模块是否实现了 Manifest 中所有 Server 能力。
+ *
+ * Admin Route 页面由 Web 构建门禁校验；这里覆盖 API、任务、Tool、AI Operation
+ * 与 Provider，且只检查 Host 安装单元，不把平台静态实现伪装成业务 Handler。
+ */
+export function validateHostedModuleImplementations(
+  installations: readonly InstallableServerModule<ModuleManifest>[],
+  hosts: InitializedModuleHosts,
+): void {
+  for (const installation of installations) {
+    const moduleName = installation.manifest.name;
+    assertComplete(
+      "API Route",
+      installation.manifest.apiPermissions.map(
+        ({ method, path }) => `${method.toUpperCase()} ${path}`,
+      ),
+      hosts.routes
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(
+          ({ definition }) =>
+            `${definition.method.toUpperCase()} ${definition.path}`,
+        )
+        .concat(
+          hosts.governedResources
+            .filter((entry) => entry.moduleName === moduleName)
+            .flatMap(({ registration }) =>
+              governedResourceRouteKeys(registration),
+            ),
+        ),
+    );
+    assertComplete(
+      "定时任务",
+      installation.manifest.tasks.map(({ key }) => key),
+      hosts.taskHandlers
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.taskKey),
+    );
+    assertComplete(
+      "Agent Tool",
+      installation.manifest.tools.map(({ key }) => key),
+      [...hosts.toolHandlers, ...hosts.sandboxToolHandlers]
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.toolKey),
+    );
+    assertComplete(
+      "AI Operation",
+      (installation.manifest.aiOperations ?? []).map(({ key }) => key),
+      hosts.aiOperationHandlers
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ registration }) => registration.operationKey),
+    );
+    assertComplete(
+      "Provider",
+      installation.manifest.providers.map(({ key }) => key),
+      hosts.searchProviders
+        .filter((entry) => entry.moduleName === moduleName)
+        .map(({ provider }) => provider.key),
+    );
+  }
+  validateDurableHandlerInstallations(hosts);
+}
+
+export function governedResourceRouteKeys(
+  registration: Pick<
+    ModuleGovernedResourceRegistration,
+    "readPath" | "revealPath" | "export"
+  >,
+): string[] {
+  return [
+    `GET ${registration.readPath}`,
+    `POST ${registration.revealPath}`,
+    ...(registration.export
+      ? [
+          `POST ${registration.export.basePath}`,
+          `GET ${registration.export.basePath}/:id`,
+          `POST ${registration.export.basePath}/:id/cancel`,
+          `GET ${registration.export.basePath}/:id/download`,
+        ]
+      : []),
+  ];
+}
+
+function assertComplete(
+  label: string,
+  declared: readonly string[],
+  registered: readonly string[],
+): void {
+  const implementations = new Set(registered);
+  for (const key of declared) {
+    if (!implementations.has(key)) {
+      throw new Error(`${label} ${key} 缺少 Handler`);
+    }
+  }
+}
+
+function validateDurableHandlerInstallations(
+  hosts: InitializedModuleHosts,
+): void {
+  const registry = new DurableHandlerRegistry();
+  hosts.installDurableHandlers(registry);
+  const hosted = hosts.durableHandlers.map(
+    ({ moduleName, definition }) => `${moduleName}:${definition.key}`,
+  );
+  const installed = registry.keys().map((key) => {
+    const handler = registry.get(key);
+    return `${handler?.moduleName ?? ""}:${key}`;
+  });
+  assertSameRegistrations("Durable Handler", hosted, installed);
+}
+
+function assertSameRegistrations(
+  label: string,
+  hosted: readonly string[],
+  installed: readonly string[],
+): void {
+  assertComplete(label, hosted, installed);
+  const declarations = new Set(hosted);
+  for (const key of installed) {
+    if (!declarations.has(key)) {
+      throw new Error(`${label} ${key} 未在 Host 注册`);
+    }
+  }
+}

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

@@ -3,6 +3,7 @@ import type { ModuleManifest } from "@southwind-ai/modules";
 import type {
   InstallableServerModule,
   ModuleAiOperationHandlerRegistration,
+  ModuleDurableHandlerDefinition,
   ModuleInitializer,
   ModuleGovernedResourceRegistration,
   ModuleRolePreset,
@@ -40,6 +41,14 @@ export interface RegisteredModuleAiOperationHandler {
   readonly registration: ModuleAiOperationHandlerRegistration;
 }
 
+export interface RegisteredModuleDurableHandler {
+  readonly moduleName: string;
+  readonly definition: Pick<
+    ModuleDurableHandlerDefinition<unknown>,
+    "key" | "featureKey" | "permissionKey" | "auditAction"
+  >;
+}
+
 export interface RegisteredModuleGovernedResource {
   readonly moduleName: string;
   readonly registration: ModuleGovernedResourceRegistration;
@@ -73,6 +82,7 @@ export interface InitializedModuleHosts {
   readonly toolHandlers: readonly RegisteredModuleToolHandler[];
   readonly sandboxToolHandlers: readonly RegisteredModuleSandboxToolHandler[];
   readonly aiOperationHandlers: readonly RegisteredModuleAiOperationHandler[];
+  readonly durableHandlers: readonly RegisteredModuleDurableHandler[];
   readonly governedResources: readonly RegisteredModuleGovernedResource[];
   readonly rolePresets: readonly RegisteredModuleRolePreset[];
   readonly searchProviders: readonly RegisteredModuleSearchProvider[];
@@ -83,5 +93,9 @@ export interface InitializedModuleHosts {
   resourceFileAccessPoliciesOf(
     moduleName: string,
   ): readonly ModuleResourceFileAccessPolicy[];
+  durableHandlerOf(
+    moduleName: string,
+    handlerKey: string,
+  ): RegisteredModuleDurableHandler["definition"] | undefined;
   installDurableHandlers(registry: DurableHandlerRegistry): void;
 }

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

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import { featureKey } from "@southwind-ai/shared";
 import type {
   ModuleInitializer,
   ModuleSandboxToolHost,
@@ -15,6 +16,9 @@ describe("模块 Host 初始化", () => {
       await Promise.resolve();
       host.registerDurableHandler({
         key: "alpha.refresh",
+        featureKey: "alpha.refresh",
+        permissionKey: "alpha.refresh.execute",
+        auditAction: "alpha.refresh.execute",
         payload: { parse: () => ({}) },
         execute: () => undefined,
       });
@@ -25,7 +29,7 @@ describe("模块 Host 初始化", () => {
     });
 
     const initialized = await initializeModuleHosts({
-      modules: [manifest("alpha"), manifest("beta")],
+      modules: [durableManifest("alpha"), manifest("beta")],
       initializers: [first, second],
     });
     expect(events).toEqual(["alpha:start", "alpha:end", "beta"]);
@@ -33,6 +37,13 @@ describe("模块 Host 初始化", () => {
     const registry = new DurableHandlerRegistry();
     initialized.installDurableHandlers(registry);
     expect(registry.keys()).toEqual(["alpha.refresh"]);
+    expect(
+      initialized.durableHandlerOf("alpha", "alpha.refresh"),
+    ).toMatchObject({
+      featureKey: "alpha.refresh",
+      permissionKey: "alpha.refresh.execute",
+      auditAction: "alpha.refresh.execute",
+    });
   });
 
   test("未知模块、错误命名空间和重复注册立即失败", async () => {
@@ -76,11 +87,14 @@ describe("模块 Host 初始化", () => {
 
     await expect(
       initializeModuleHosts({
-        modules: [manifest("known")],
+        modules: [durableManifest("known")],
         initializers: [
           initializer("known", (host) => {
             const definition = {
               key: "known.refresh",
+              featureKey: "known.refresh",
+              permissionKey: "known.refresh.execute",
+              auditAction: "known.refresh.execute",
               payload: { parse: () => ({}) },
               execute: () => undefined,
             };
@@ -92,6 +106,26 @@ describe("模块 Host 初始化", () => {
     ).rejects.toThrow("任务 handler 重复注册：known.refresh");
   });
 
+  test("Durable Handler 必须绑定 Manifest 已声明能力", async () => {
+    await expect(
+      initializeModuleHosts({
+        modules: [durableManifest("known")],
+        initializers: [
+          initializer("known", (host) => {
+            host.registerDurableHandler({
+              key: "known.refresh",
+              featureKey: "known.missing",
+              permissionKey: "known.refresh.execute",
+              auditAction: "known.refresh.execute",
+              payload: { parse: () => ({}) },
+              execute: () => undefined,
+            });
+          }),
+        ],
+      }),
+    ).rejects.toThrow("任务 handler Feature 未在 Manifest 注册：known.missing");
+  });
+
   test("安装单元的 Manifest 必须来自同一平台能力目录", async () => {
     await expect(
       initializeModuleHosts({
@@ -238,3 +272,45 @@ function policy(purpose: string) {
     signature: "none" as const,
   };
 }
+
+function durableManifest(name: string) {
+  const capabilityKey = `${name}.refresh`;
+  const permissionKey = `${capabilityKey}.execute`;
+  return manifest(name, {
+    features: [
+      {
+        key: featureKey(capabilityKey),
+        label: "刷新",
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    permissions: [
+      {
+        key: permissionKey,
+        label: "执行刷新",
+        module: name,
+        moduleLabel: name,
+        resource: "refresh",
+        resourceLabel: "刷新",
+        action: "execute",
+      },
+    ],
+    tasks: [
+      {
+        key: capabilityKey,
+        label: "刷新",
+        description: "刷新模块数据。",
+        featureKey: capabilityKey,
+        permissionKey,
+        auditAction: permissionKey,
+        intervalSeconds: 60,
+        maxAttempts: 3,
+        retryDelaySeconds: 5,
+      },
+    ],
+    auditActions: [permissionKey],
+  });
+}

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