create-windy 0.8.3 → 0.10.0

package/template/apps/server/src/media-runtime/media-only-composition.ts

@@ -0,0 +1,44 @@
+import type { SystemRepositories } from "../system/seed.js";
+import { resolveCurrentSystemActor } from "../system/actor.js";
+import {
+  createManifestAuthorizedRouteApp,
+  createStaticRouteAuthorizer,
+} from "../module-host/static-route-authorization.js";
+import { requiredEnvironment } from "./required-environment.js";
+import { composeSharedAiRuntime } from "./shared-composition.js";
+
+type SharedInput = Parameters<typeof composeSharedAiRuntime>[0];
+
+export function composeMediaOnlyRuntime(
+  input: Omit<
+    SharedInput,
+    "internalToken" | "secret" | "resolveActor" | "agent"
+  > & {
+    enableAI: boolean;
+    systemRepositories: SystemRepositories;
+  },
+) {
+  if (
+    !input.enableAI ||
+    (input.switches?.document === false &&
+      input.switches.speech === false &&
+      input.switches.embedding === false)
+  )
+    return undefined;
+
+  const authorizer = createStaticRouteAuthorizer(input.runtime, input.modules);
+  const shared = composeSharedAiRuntime({
+    ...input,
+    app: createManifestAuthorizedRouteApp(input.app, authorizer),
+    internalToken: requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN"),
+    secret: requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET"),
+    resolveActor: (actorId) =>
+      resolveCurrentSystemActor(input.systemRepositories, actorId),
+  });
+  const ports = shared.modulePorts();
+  return {
+    aiArtifacts: shared.aiArtifacts,
+    aiOperations: ports.operations,
+    aiReadiness: ports.readiness,
+  };
+}

package/template/apps/server/src/media-runtime/module-ai-port-factory.test.ts

@@ -0,0 +1,69 @@
+import { expect, test } from "bun:test";
+import { systemModuleManifest } from "@southwind-ai/modules";
+import {
+  operationKey,
+  readinessManifest,
+  readySnapshot,
+} from "../ai-runtime-readiness/operation-port.test-support.js";
+import { AiRuntimeReadinessTrustStoreV1 } from "../ai-runtime-readiness/trust-store.js";
+import { createServerRuntime } from "../runtime.js";
+import { createModuleAiPorts } from "./module-ai-port-factory.js";
+
+test("已授权的业务 Operation 在 Document Feature 关闭时不探测远端", async () => {
+  const modules = [
+    readinessManifest(),
+    systemModuleManifest("system.media-runtime"),
+  ];
+  const featureCatalog = modules.flatMap((module) => module.features);
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog,
+      disabledFeatureKeys: new Set(["system.document"]),
+      licenseEnforced: false,
+    },
+  );
+  const context = await runtime.createGuardContextForActor(
+    new Request("http://localhost/evidence"),
+    {
+      id: "ocr-operator",
+      type: "user",
+      name: "OCR operator",
+      roleCodes: [],
+      permissionKeys: ["evidence.document.ocr.execute"],
+    },
+  );
+  let probes = 0;
+  const ports = createModuleAiPorts({
+    modules,
+    runtime,
+    sources: [
+      {
+        kind: "document",
+        async health() {
+          probes += 1;
+          return Response.json(readySnapshot());
+        },
+      },
+    ],
+    operations: { modules },
+    trustStore: new AiRuntimeReadinessTrustStoreV1(),
+  });
+  const signal = AbortSignal.timeout(1_000);
+  await expect(
+    ports.readiness("evidence", context, signal).inspect({ operationKey }),
+  ).resolves.toMatchObject({
+    runtimeKind: "document",
+    status: "unavailable",
+    unavailableReasons: [{ code: "RUNTIME_NOT_CONFIGURED" }],
+  });
+  expect(probes).toBe(0);
+  await expect(
+    ports.operations("evidence", context, signal).startDocument({
+      operationKey,
+      sources: [],
+      options: {},
+      idempotencyKey: "regression",
+    }),
+  ).rejects.toMatchObject({ code: "AI_OPERATION_UNAVAILABLE" });
+});

package/template/apps/server/src/media-runtime/module-ai-port-factory.ts

@@ -0,0 +1,72 @@
+import type { AiRuntimeKind } from "@southwind-ai/shared";
+import { ModuleAiOperationError } from "@southwind-ai/server-sdk";
+import { evaluateFeatureGuard } from "../guards.js";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { createModuleAiOperationReadinessPort } from "../ai-runtime-readiness/operation-port.js";
+import type { AiRuntimeReadinessTrustStoreV1 } from "../ai-runtime-readiness/trust-store.js";
+import { createModuleAiOperationPort } from "../module-host/ai-operation-port.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type OperationRuntime = Parameters<typeof createModuleAiOperationPort>[3];
+type ReadinessInput = Parameters<
+  typeof createModuleAiOperationReadinessPort
+>[0];
+
+export function createModuleAiPorts(input: {
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly sources: ReadinessInput["sources"];
+  readonly trustStore: AiRuntimeReadinessTrustStoreV1;
+  readonly operations: OperationRuntime;
+}) {
+  const features = new Map(
+    input.modules.flatMap((module) =>
+      module.features.map((feature) => [String(feature.key), feature] as const),
+    ),
+  );
+  const runtimeAllowed = async (
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    kind: AiRuntimeKind,
+  ) => {
+    const feature = features.get(`system.${kind}`);
+    if (!feature) return false;
+    const decision = evaluateFeatureGuard(
+      guardContext,
+      await input.runtime.resolveFeature(guardContext, feature),
+    );
+    if (!decision.allowed) input.runtime.recordDecisions([decision]);
+    return decision.allowed;
+  };
+  const operations = (
+    moduleName: string,
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    signal: AbortSignal,
+  ) =>
+    createModuleAiOperationPort(moduleName, guardContext, signal, {
+      ...input.operations,
+      async requireFeature(kind) {
+        if (!(await runtimeAllowed(guardContext, kind))) {
+          throw new ModuleAiOperationError(
+            "AI_OPERATION_UNAVAILABLE",
+            `${kind} Feature 未启用`,
+          );
+        }
+      },
+    });
+  const readiness = (
+    moduleName: string,
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    signal: AbortSignal,
+  ) =>
+    createModuleAiOperationReadinessPort({
+      moduleName,
+      guardContext,
+      signal,
+      modules: input.modules,
+      sources: input.sources,
+      trustStore: input.trustStore,
+      runtimeAllowed: (kind) => runtimeAllowed(guardContext, kind),
+      runtime: input.runtime,
+    });
+  return { operations, readiness };
+}

package/template/apps/server/src/{agent → media-runtime}/runtime-readiness-sources.ts

@@ -1,3 +1,4 @@
+import type { AiRuntimeSwitches } from "@southwind-ai/shared";
 import type { AiRuntimeReadinessSourceV1 } from "../ai-runtime-readiness/operation-port.js";
 
 interface HealthPort {
@@ -5,16 +6,22 @@ interface HealthPort {
 }
 
 export function createAiRuntimeReadinessSources(input: {
-  agent: HealthPort;
+  agent?: HealthPort;
   document: HealthPort;
   speech: HealthPort;
   embedding: HealthPort;
+  switches?: AiRuntimeSwitches;
 }): readonly AiRuntimeReadinessSourceV1[] {
-  return [
-    {
-      kind: "agent",
-      health: (signal) => input.agent.health(signal),
-    },
+  const agent = input.agent;
+  const sources: AiRuntimeReadinessSourceV1[] = [
+    ...(agent
+      ? [
+          {
+            kind: "agent" as const,
+            health: (signal?: AbortSignal) => agent.health(signal),
+          },
+        ]
+      : []),
     {
       kind: "document",
       health: (signal) => input.document.health(signal),
@@ -28,4 +35,5 @@ export function createAiRuntimeReadinessSources(input: {
       health: (signal) => input.embedding.health(signal),
     },
   ];
+  return sources.filter(({ kind }) => input.switches?.[kind] !== false);
 }

package/template/apps/server/src/media-runtime/shared-composition.ts

@@ -0,0 +1,104 @@
+import { AiArtifactCodec } from "../ai-artifact/codec.js";
+import { registerAiArtifactRoutes } from "../ai-artifact/routes.js";
+import { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { createModuleAiOperationReadinessPort } from "../ai-runtime-readiness/operation-port.js";
+import { AiRuntimeReadinessTrustStoreV1 } from "../ai-runtime-readiness/trust-store.js";
+import { connectMediaRuntimes, registerMediaRuntimes } from "./composition.js";
+import { ExecutionGrantStore } from "../ai-runtime-security/execution-grants.js";
+import type {
+  AiRuntimeSwitches,
+  FeatureFlagDefinition,
+} from "@southwind-ai/shared";
+import { createAiRuntimeReadinessSources } from "./runtime-readiness-sources.js";
+import { createModuleAiPorts } from "./module-ai-port-factory.js";
+
+type MediaInput = Parameters<typeof registerMediaRuntimes>[0];
+type OperationServices = Parameters<
+  typeof createModuleAiPorts
+>[0]["operations"];
+
+export function composeSharedAiRuntime(
+  input: Pick<
+    MediaInput,
+    | "modules"
+    | "hosts"
+    | "runtime"
+    | "storage"
+    | "db"
+    | "resolveActor"
+    | "internalToken"
+  > & {
+    app: MediaInput["aiRouteApp"];
+    switches?: AiRuntimeSwitches;
+    features: readonly FeatureFlagDefinition[];
+    secret: string;
+    agent?: Parameters<typeof createAiRuntimeReadinessSources>[0]["agent"];
+  },
+) {
+  const aiArtifacts = new AiArtifactRuntime(
+    new AiArtifactCodec(input.secret),
+    input.hosts,
+    input.runtime,
+    input.features,
+    input.storage,
+    input.resolveActor,
+  );
+  registerAiArtifactRoutes(input.app, aiArtifacts, input.internalToken);
+  const grants = new ExecutionGrantStore();
+  const media = connectMediaRuntimes(input.internalToken, input.switches);
+  const { documentRemote, speechRemote, embeddingRemote } = media;
+  const readinessSources = createAiRuntimeReadinessSources({
+    agent: input.agent,
+    document: documentRemote,
+    speech: speechRemote,
+    embedding: embeddingRemote,
+    switches: input.switches,
+  });
+  const readinessTrustStore = new AiRuntimeReadinessTrustStoreV1();
+  const aiReadiness = createModuleAiOperationReadinessPort({
+    modules: input.modules,
+    sources: readinessSources,
+    trustStore: readinessTrustStore,
+    runtime: input.runtime,
+  });
+  const { documentFacadeWithOutput, speechFacade, embeddingFacade } =
+    registerMediaRuntimes({
+      ...media,
+      switches: input.switches,
+      modules: input.modules,
+      hosts: input.hosts,
+      runtime: input.runtime,
+      storage: input.storage,
+      db: input.db,
+      aiReadiness,
+      resolveActor: input.resolveActor,
+      aiArtifacts,
+      grants,
+      aiRouteApp: input.app,
+      internalToken: input.internalToken,
+    });
+
+  return {
+    aiArtifacts,
+    catalogReadiness: aiReadiness,
+    modulePorts(
+      agent: Pick<OperationServices, "agentFacade" | "agentRemote"> = {},
+    ) {
+      return createModuleAiPorts({
+        modules: input.modules,
+        runtime: input.runtime,
+        sources: readinessSources,
+        trustStore: readinessTrustStore,
+        operations: {
+          ...agent,
+          documentFacade: documentFacadeWithOutput,
+          documentRemote,
+          speechFacade,
+          speechRemote,
+          embeddingFacade,
+          modules: input.modules,
+        },
+      });
+    },
+  };
+}

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

@@ -5,6 +5,29 @@ import { Elysia } from "elysia";
 import { validateServerModuleComposition } from "./module-composition.js";
 
 describe("Server Module Composition", () => {
+  test("WebSocket 实际注册以 GET 握手校验，未知 Socket 仍拒绝", () => {
+    const path = "/api/auth/users/:id/password";
+    const module = fixture();
+    module.apiPermissions[0]!.method = "GET";
+    const app = new Elysia({ prefix: "/api" }).ws("/auth/users/:id/password", {
+      message() {},
+    });
+    expect(app.routes[0]!.method).toBe("WS");
+    expect(() =>
+      validateServerModuleComposition({
+        modules: [module],
+        routes: app.routes,
+      }),
+    ).not.toThrow();
+    expect(() =>
+      validateServerModuleComposition({
+        modules: [module],
+        routes: [...app.routes, { method: "WS", path: "/api/unregistered" }],
+      }),
+    ).toThrow("HTTP Route 已注册但未在 Manifest 声明：GET /api/unregistered");
+    expect(app.routes[0]!.path).toBe(path);
+  });
+
   test("以 Elysia 实际注册路由作为 API Handler 事实源", () => {
     const app = new Elysia({ prefix: "/api" }).post(
       "/auth/users/:id/password",
@@ -30,6 +53,28 @@ describe("Server Module Composition", () => {
     ).toThrow("API Route Handler Key 重复：POST /api/auth/users/:id/password");
   });
 
+  test("启动配置关闭的能力可省略 Handler，启用能力仍须完整注册", () => {
+    const module = fixture();
+    const feature = module.apiPermissions[0]!.featureKey!;
+    const input = { modules: [module], routes: [] };
+    expect(() => validateServerModuleComposition(input)).toThrow(
+      "缺少 Handler",
+    );
+    expect(() =>
+      validateServerModuleComposition({
+        ...input,
+        disabledFeatureKeys: new Set([feature]),
+      }),
+    ).not.toThrow();
+    expect(() =>
+      validateServerModuleComposition({
+        ...input,
+        routes: [{ method: "GET", path: "/api/unregistered" }],
+        disabledFeatureKeys: new Set([feature]),
+      }),
+    ).toThrow("未在 Manifest 声明");
+  });
+
   test("Host 注册实现必须在 Manifest 声明", () => {
     const app = new Elysia({ prefix: "/api" }).post(
       "/auth/users/:id/password",

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

@@ -28,6 +28,7 @@ export interface ServerCompositionInput {
    * 产品、运维、认证与恢复入口仍必须进入 Manifest。
    */
   frameworkRoutes?: readonly string[];
+  disabledFeatureKeys?: ReadonlySet<string>;
   tasks?: readonly { key: string }[];
   tools?: ReadonlyMap<string, unknown>;
   aiOperations?: readonly string[];
@@ -38,13 +39,50 @@ export interface ServerCompositionInput {
 export function validateServerModuleComposition(
   input: ServerCompositionInput,
 ): void {
+  // Elysia 将升级路由记为 WS；权限绑定使用真实 HTTP 握手方法 GET。
+  const apiRoutes = input.routes.map((route) =>
+    apiRouteKey({
+      ...route,
+      method: route.method.toUpperCase() === "WS" ? "GET" : route.method,
+    }),
+  );
   validateHttpRouteRegistration(
     input.modules,
-    input.routes.map(apiRouteKey),
+    apiRoutes,
     input.frameworkRoutes ?? [],
   );
+  const disabledFeatures = disabledRuntimeFeatureClosure(
+    input.modules,
+    input.disabledFeatureKeys,
+  );
+  const registered = new Set(apiRoutes);
+  const outputPrefix = "/api/internal/ai/output-artifacts";
+  const hasOutputSink = input.routes.some(({ path }) =>
+    path.startsWith(outputPrefix),
+  );
+  const unavailableApiRoutes = new Set(
+    input.modules.flatMap((module) =>
+      module.apiPermissions
+        .filter(
+          ({ featureKey, path }) =>
+            (featureKey !== undefined && disabledFeatures.has(featureKey)) ||
+            (!hasOutputSink &&
+              featureKey === "system.ai-artifact" &&
+              path.startsWith(outputPrefix)),
+        )
+        .map(apiRouteKey)
+        .filter((key) => !registered.has(key)),
+    ),
+  );
+  const unavailableTools = disabledFeatures.has("system.agent")
+    ? new Set(
+        input.modules.flatMap((module) => module.tools.map(({ key }) => key)),
+      )
+    : undefined;
   validateModuleComposition(input.modules, {
-    apiRoutes: input.routes.map(apiRouteKey),
+    unavailableApiRoutes,
+    unavailableTools,
+    apiRoutes,
     tasks: (input.tasks || []).map(({ key }) => key),
     tools: [...(input.tools?.keys() || [])],
     aiOperations: input.aiOperations,
@@ -55,6 +93,23 @@ export function validateServerModuleComposition(
   }
 }
 
+function disabledRuntimeFeatureClosure(
+  modules: readonly ModuleManifest[],
+  disabledKeys: ReadonlySet<string> | undefined,
+) {
+  const disabled = new Set(disabledKeys);
+  const features = modules.flatMap((module) => module.features);
+  let previousSize = -1;
+  while (previousSize !== disabled.size) {
+    previousSize = disabled.size;
+    for (const feature of features) {
+      if (feature.dependencies?.some((key) => disabled.has(key)))
+        disabled.add(feature.key);
+    }
+  }
+  return disabled;
+}
+
 function validateHttpRouteRegistration(
   modules: readonly ModuleManifest[],
   registeredRoutes: readonly string[],