create-windy 0.5.1 → 0.6.0

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

@@ -4,10 +4,15 @@ import type {
   ModuleActor,
   ModuleAiArtifactPort,
   ModuleAiOperationPort,
+  ModuleAiOperationReadinessPortV1,
+  ModuleAiScreenshotIntakePortV1,
   ModuleAuditEmitInput,
   ModuleAuditEmitter,
   ModuleRequestContext,
+  ModuleReportStagingPortV1,
+  ModuleSecretPort,
   ModuleStoragePort,
+  ModuleStorageWritePortV1,
   ModuleUserDirectoryPort,
 } from "@southwind-ai/server-sdk";
 import {
@@ -26,11 +31,13 @@ import {
   type RequestGuardContext,
 } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
-import { unavailableModuleStoragePort } from "./storage-port.js";
 import {
   createModuleJobPort,
   type ModuleJobControlRuntime,
 } from "./job-port.js";
+import { unavailableModuleSecretPort } from "./module-secret-port.js";
+import { unavailableModuleStoragePort } from "./storage-port.js";
+import { unavailableModuleStorageWritePort } from "./storage-write-unavailable.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -83,14 +90,21 @@ export interface ModuleRequestContextInput {
   params: Record<string, string | undefined>;
   query: Record<string, string | undefined>;
   body?: unknown;
+  bodyStream?: ReadableStream<Uint8Array>;
+  signal?: AbortSignal;
   runtime: ServerRuntime;
   jobs?: DurableJobs;
   jobControl?: ModuleJobControlRuntime;
   reauthorizeJobs?: () => Promise<boolean>;
+  secrets?: ModuleSecretPort;
   storage?: ModuleStoragePort;
+  storageWriter?: ModuleStorageWritePortV1;
+  reportStaging?: ModuleReportStagingPortV1;
   userDirectory?: ModuleUserDirectoryPort;
   aiArtifacts?: ModuleAiArtifactPort;
   aiOperations?: ModuleAiOperationPort;
+  aiReadiness?: ModuleAiOperationReadinessPortV1;
+  screenshots?: ModuleAiScreenshotIntakePortV1;
   onAuditEmit?: (action: string) => void;
 }
 
@@ -99,15 +113,21 @@ export function buildModuleRequestContext(
 ): ModuleRequestContext {
   return {
     requestId: input.guardContext.requestId,
+    signal: input.signal ?? new AbortController().signal,
     actor: toModuleActor(input.guardContext.actor),
     params: input.params,
     query: input.query,
     body: input.body,
+    bodyStream: input.bodyStream,
     audit: createModuleAuditEmitter(input),
     aiArtifacts:
       input.aiArtifacts ?? unavailableModuleAiArtifactPort(input.moduleName),
     aiOperations:
       input.aiOperations ?? unavailableModuleAiOperationPort(input.moduleName),
+    aiReadiness: input.aiReadiness ?? unavailableModuleAiReadinessPort(),
+    ...(input.screenshots
+      ? { screenshots: narrowModuleScreenshotIntakePort(input.screenshots) }
+      : {}),
     jobs: createModuleJobPort({
       moduleName: input.moduleName,
       guardContext: input.guardContext,
@@ -116,12 +136,49 @@ export function buildModuleRequestContext(
       control: input.jobControl,
       reauthorize: input.reauthorizeJobs,
     }),
+    secrets: input.secrets ?? unavailableModuleSecretPort(),
     storage: input.storage ?? unavailableModuleStoragePort(input.moduleName),
+    storageWriter:
+      input.storageWriter ??
+      unavailableModuleStorageWritePort(input.moduleName),
+    reportStaging: input.reportStaging,
     userDirectory:
       input.userDirectory ?? unavailableModuleUserDirectory(input.moduleName),
   };
 }
 
+function unavailableModuleAiReadinessPort(): ModuleAiOperationReadinessPortV1 {
+  return {
+    async inspect({ operationKey }) {
+      return {
+        schemaVersion: 1,
+        operationKey,
+        runtimeKind: "agent",
+        observedAt: new Date().toISOString(),
+        status: "unavailable",
+        deployment: null,
+        offers: [],
+        unavailableReasons: [
+          { code: "RUNTIME_NOT_CONFIGURED", retryable: true },
+        ],
+      };
+    },
+  };
+}
+
+function narrowModuleScreenshotIntakePort(
+  input: ModuleAiScreenshotIntakePortV1 | undefined,
+): ModuleAiScreenshotIntakePortV1 | undefined {
+  if (!input) return;
+  const narrowed: ModuleAiScreenshotIntakePortV1 = {
+    create: (value) => input.create(value),
+    bind: (value) => input.bind(value),
+    discard: (value) => input.discard(value),
+    cancel: (value) => input.cancel(value),
+  };
+  return Object.freeze(narrowed);
+}
+
 function unavailableModuleAiOperationPort(
   moduleName: string,
 ): ModuleAiOperationPort {

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

@@ -10,6 +10,13 @@ export function validateRouteDeclaration(
       item.method === definition.method && item.path === definition.path,
   );
   const route = `${definition.method} ${definition.path}`;
+  if (
+    definition.bodyMode === "stream" &&
+    definition.method !== "POST" &&
+    definition.method !== "PUT"
+  ) {
+    throw new Error(`模块流式路由仅支持 POST/PUT：${route}`);
+  }
   if (!binding) {
     throw new Error(`模块路由未在 Manifest 声明：${route}`);
   }
@@ -37,9 +44,7 @@ export function validateRouteDeclaration(
     definition.auditAction !== undefined &&
     definition.auditAction !== binding.auditAction
   ) {
-    throw new Error(
-      `模块路由审计动作与 Manifest 声明不一致：${route}`,
-    );
+    throw new Error(`模块路由审计动作与 Manifest 声明不一致：${route}`);
   }
   if (
     binding.auditAction &&
@@ -49,6 +54,8 @@ export function validateRouteDeclaration(
         : action.key === binding.auditAction,
     )
   ) {
-    throw new Error(`模块路由审计动作未在 Manifest 注册：${binding.auditAction}`);
+    throw new Error(
+      `模块路由审计动作未在 Manifest 注册：${binding.auditAction}`,
+    );
   }
 }

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

@@ -0,0 +1,246 @@
+import type { DurableJobs, SubmitDurableJob } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  ModuleInitializer,
+  ModuleRequestContext,
+} from "@southwind-ai/server-sdk";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { createReportStagingRuntime } from "../report-staging/runtime.js";
+import { createServerRuntime } from "../runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { installModuleRoutes } from "./route-installer.js";
+
+interface FixtureOptions {
+  permissionKeys?: string[];
+  featureEnabled?: boolean;
+  withJobs?: boolean;
+  withStorage?: boolean;
+  withReportStaging?: boolean;
+  productionWithoutDb?: boolean;
+}
+
+export async function createRouteInstallerFixture(
+  options: FixtureOptions = {},
+) {
+  const state: {
+    handled: boolean;
+    context?: ModuleRequestContext;
+    submittedJob?: SubmitDurableJob;
+  } = { handled: false };
+  const initializer: ModuleInitializer = {
+    moduleName: "shop",
+    initialize(host) {
+      host.registerUploadPolicy({
+        purpose: "shop.attachment",
+        maxByteSize: 1024,
+        maxPartByteSize: 512,
+        sessionTtlMs: 60_000,
+        allowedTypes: { "text/plain": ["txt"] },
+        signature: "none",
+      });
+      if (options.withReportStaging) {
+        host.registerReportStagingPolicy(reportStagingPolicy());
+      }
+      host.registerRoutes([
+        {
+          method: "GET",
+          path: "/api/shop/items",
+          permissionKey: "shop.item.read",
+          handler: (context) => {
+            state.handled = true;
+            state.context = context;
+            return { items: [] };
+          },
+        },
+        {
+          method: "POST",
+          path: "/api/shop/items",
+          permissionKey: "shop.item.manage",
+          handler: () => {
+            state.handled = true;
+            state.context = undefined;
+            return { ok: true };
+          },
+        },
+      ]);
+    },
+  };
+  const hosts = await initializeModuleHosts({
+    modules: [shopManifest()],
+    initializers: [initializer],
+  });
+  let currentPermissions = options.permissionKeys;
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor(currentPermissions) },
+      licenseResolver: {
+        resolve: () => ({ versionKey: licenseVersionKey("standard") }),
+      },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: options.featureEnabled ?? true,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const jobs = options.withJobs
+    ? ({
+        submit: (input: SubmitDurableJob) => {
+          state.submittedJob = input;
+          return Promise.resolve({
+            job: { id: "job_1" },
+            created: true,
+          });
+        },
+      } as unknown as DurableJobs)
+    : undefined;
+  const app = new FakeRouteApp();
+  const storage = options.withStorage
+    ? createStorageRuntime({}, undefined, hosts.uploadPolicies)
+    : undefined;
+  const reportStaging = options.withReportStaging
+    ? createReportStagingRuntime(
+        { NODE_ENV: options.productionWithoutDb ? "production" : undefined },
+        undefined,
+      )
+    : undefined;
+  installModuleRoutes(hosts, app, {
+    runtime,
+    features: shopManifest().features,
+    jobs,
+    storage: storage
+      ? { uploads: storage.uploads, files: storage.files }
+      : undefined,
+    reportStaging,
+  });
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/shop/items"),
+  );
+  return {
+    runtime,
+    get handled() {
+      return state.handled;
+    },
+    get context() {
+      return state.context;
+    },
+    get submittedJob() {
+      return state.submittedJob;
+    },
+    storage,
+    setPermissions(permissionKeys: string[]) {
+      currentPermissions = permissionKeys;
+    },
+    invoke(method: string, path: string, params = {}, body?: unknown) {
+      return app.invoke(method, path, {
+        guardContext,
+        request: new Request(`http://localhost${path}`),
+        params,
+        query: {},
+        body,
+      });
+    },
+  };
+}
+
+function reportStagingPolicy() {
+  return {
+    purpose: "shop.report-staging",
+    sourcePurposes: ["shop.attachment"],
+    retentionMs: 60_000,
+    claimTtlMs: 30_000,
+    maxReadLeaseMs: 10_000,
+    maxProcessMs: 10_000,
+    maxSources: 4,
+    maxArchiveBytes: 1_024,
+    maxExpandedBytes: 4_096,
+    maxEntryBytes: 2_048,
+    maxEntries: 20,
+    maxCompressionRatio: 100,
+    maxPathDepth: 8,
+  };
+}
+
+function actor(
+  permissionKeys = ["shop.item.read", "shop.item.manage"],
+): RequestActor {
+  return {
+    id: "user_admin",
+    type: "user",
+    name: "测试管理员",
+    roleCodes: ["developer"],
+    permissionKeys,
+    scopeContext: buildScopeContext("user_admin", undefined, [
+      {
+        id: "developer",
+        code: "developer",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function shopManifest(): ModuleManifest {
+  return {
+    name: "shop",
+    version: "0.1.0",
+    label: "商店",
+    description: "测试模块",
+    menus: [],
+    adminRoutes: [],
+    permissions: [permission("shop.item.read"), permission("shop.item.manage")],
+    apiPermissions: [
+      {
+        method: "GET",
+        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: [
+      {
+        key: featureKey("shop.feature"),
+        label: "商店",
+        module: "shop",
+        description: "测试 Feature",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: ["crud.create", "data.read"],
+  };
+}
+
+function permission(key: string) {
+  return {
+    key,
+    label: key,
+    module: "shop",
+    moduleLabel: "商店",
+    resource: "item",
+    resourceLabel: "商品",
+    action: key.endsWith("read") ? ("read" as const) : ("manage" as const),
+  };
+}