create-windy 0.3.18 → 0.4.0

package/template/apps/server/src/agent/routes.ts

@@ -14,6 +14,7 @@ import {
   type ModuleToolHandlers,
   type PlatformToolExecutionContext,
 } from "./tool-registry.js";
+import type { StaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -85,9 +86,16 @@ export function createSystemToolHandlers(
 export function registerAgentRoutes(
   app: RouteApp,
   registry: GovernedToolRegistry,
+  authorizer: StaticRouteAuthorizer,
 ) {
   app.get("/agent/tools", async (rawContext) => {
     const { guardContext } = rawContext as RouteContext;
+    const denied = await authorizer.authorize(
+      guardContext,
+      "GET",
+      "/api/agent/tools",
+    );
+    if (denied) return denied;
     return Promise.all(
       registry.definitions().map(async (tool) => ({
         key: tool.key,
@@ -103,6 +111,12 @@ export function registerAgentRoutes(
 
   app.post("/agent/tools/:key/execute", async (rawContext) => {
     const context = rawContext as RouteContext;
+    const denied = await authorizer.authorize(
+      context.guardContext,
+      "POST",
+      "/api/agent/tools/:key/execute",
+    );
+    if (denied) return denied;
     try {
       return await registry.execute(
         context.params.key ?? "",

package/template/apps/server/src/agent/runtime-bootstrap.ts

@@ -46,6 +46,11 @@ import { AgentBackgroundOperationExecutor } from "./background-operation.js";
 import type { DeferredAgentBackgroundOperationPortFactory } from "./background-operation-port.js";
 import { UnixSandboxToolClient } from "./sandbox-client.js";
 import { createModuleAiOperationPort } from "../module-host/ai-operation-port.js";
+import {
+  createManifestAuthorizedRouteApp,
+  createStaticRouteAuthorizer,
+} from "../module-host/static-route-authorization.js";
+import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
 
 export function registerAgentPlatformRuntime(input: {
   app: RouteApp;
@@ -79,18 +84,29 @@ export function registerAgentPlatformRuntime(input: {
     toolHandlers,
     input.runtime,
   );
-  registerAgentRoutes(input.app, toolRegistry);
+  const routeAuthorizer = createStaticRouteAuthorizer(
+    input.runtime,
+    input.modules,
+  );
+  registerAgentRoutes(input.app, toolRegistry, routeAuthorizer);
   registerMcpRoutes(
     input.app,
     new PlatformMcpAdapter(toolRegistry, input.runtime, features),
   );
   if (!input.platformConfig.enableAI) {
+    registerUnavailableAiRoutes(
+      createManifestAuthorizedRouteApp(input.app, routeAuthorizer),
+    );
     return {
       toolHandlers,
       aiArtifacts: undefined,
       aiOperations: undefined,
     };
   }
+  const aiRouteApp = createManifestAuthorizedRouteApp(
+    input.app,
+    routeAuthorizer,
+  );
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
   const aiArtifacts = new AiArtifactRuntime(
     new AiArtifactCodec(requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET")),
@@ -100,7 +116,7 @@ export function registerAgentPlatformRuntime(input: {
     input.storage,
     resolveAgentActor,
   );
-  registerAiArtifactRoutes(input.app, aiArtifacts, internalToken);
+  registerAiArtifactRoutes(aiRouteApp, aiArtifacts, internalToken);
   const remote = new RemoteAgentRuntime({
     baseUrl: process.env.AGENT_SERVER_URL || "http://agent-server:8080",
     internalToken,
@@ -127,7 +143,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
     grants,
   );
-  registerDocumentRunRoutes(input.app, documentFacade, documentRemote);
+  registerDocumentRunRoutes(aiRouteApp, documentFacade, documentRemote);
   const speechRemote = process.env.SPEECH_SERVER_URL?.trim()
     ? new RemoteSpeechRuntime({
         baseUrl: process.env.SPEECH_SERVER_URL,
@@ -142,7 +158,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
     grants,
   );
-  registerSpeechRunRoutes(input.app, speechFacade, speechRemote);
+  registerSpeechRunRoutes(aiRouteApp, speechFacade, speechRemote);
   const embeddingRemote = process.env.EMBEDDING_SERVER_URL?.trim()
     ? new RemoteEmbeddingRuntime({
         baseUrl: process.env.EMBEDDING_SERVER_URL,
@@ -156,7 +172,7 @@ export function registerAgentPlatformRuntime(input: {
     embeddingRemote,
     aiArtifacts,
   );
-  registerEmbeddingRoutes(input.app, embeddingFacade);
+  registerEmbeddingRoutes(aiRouteApp, embeddingFacade);
   const agentFacade = new AgentRunFacade(
     input.modules,
     input.hosts,
@@ -166,7 +182,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
   );
   registerAgentRunRoutes(
-    input.app,
+    aiRouteApp,
     agentFacade,
     remote,
     new RestrictedAgentToolHost(

package/template/apps/server/src/agent/sandbox-worker.ts

@@ -1,6 +1,6 @@
-import { installedBusinessModules } from "../installed-business-modules.js";
 import { SandboxToolRegistry } from "./sandbox-registry.js";
 import { runSandboxWorkerUntilSignal } from "./sandbox-worker-server.js";
+import { runtimeBusinessModules } from "../module-host/runtime-composition.js";
 
 const socketPath =
   process.env.TOOL_SANDBOX_SOCKET?.trim() ||
@@ -8,5 +8,5 @@ const socketPath =
 
 await runSandboxWorkerUntilSignal(
   socketPath,
-  new SandboxToolRegistry(installedBusinessModules),
+  new SandboxToolRegistry(runtimeBusinessModules),
 );

package/template/apps/server/src/agent/unavailable-routes.ts

@@ -0,0 +1,33 @@
+import type { RouteApp } from "../system/route-types.js";
+
+const unavailableRoutes = [
+  ["GET", "/internal/ai/artifacts"],
+  ["POST", "/document/runs"],
+  ["GET", "/document/runs/:runId/events"],
+  ["GET", "/document/runs/:runId/result"],
+  ["POST", "/document/runs/:runId/cancel"],
+  ["POST", "/speech/runs"],
+  ["GET", "/speech/runs/:runId/events"],
+  ["GET", "/speech/runs/:runId/result"],
+  ["GET", "/speech/runs/:runId/artifact"],
+  ["POST", "/speech/runs/:runId/cancel"],
+  ["POST", "/embeddings"],
+  ["POST", "/agent/runs"],
+  ["GET", "/agent/runs/:runId/events"],
+  ["GET", "/agent/runs/:runId/result"],
+  ["POST", "/agent/runs/:runId/cancel"],
+  ["POST", "/agent/runs/:runId/attach"],
+  ["POST", "/internal/agent/tools/execute"],
+] as const;
+
+export function registerUnavailableAiRoutes(app: RouteApp): void {
+  const unavailable = () =>
+    Response.json(
+      { code: "RUNTIME_UNAVAILABLE", message: "AI Runtime 未启用" },
+      { status: 503 },
+    );
+  for (const [method, path] of unavailableRoutes) {
+    if (method === "GET") app.get(path, unavailable);
+    else app.post(path, unavailable);
+  }
+}

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

@@ -0,0 +1,56 @@
+import moduleAssembly from "../../../../windy.modules.json";
+import {
+  defineWindyServerComposition,
+  type WindyServerModuleAdapter,
+  type WindyServerModuleAttachment,
+} from "@southwind-ai/server-sdk";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ManagedDepartment } from "../system/entities.js";
+import type { EntityRepository } from "../system/repository.js";
+// @windy-module work-order begin
+import { createWorkOrderModule } from "../example-modules.js";
+// @windy-module work-order end
+
+export interface ProjectBusinessModuleRuntime {
+  readonly db?: NodePgDatabase;
+  readonly departments: EntityRepository<ManagedDepartment>;
+}
+
+// @windy-module work-order begin
+const workOrderModule = createWorkOrderModule();
+// @windy-module work-order end
+
+const projectAdapters: readonly WindyServerModuleAdapter<ModuleManifest>[] = [
+  // @windy-module work-order begin
+  {
+    name: "work-order",
+    hostRange: "^0.1.0",
+    runtimeMode: "project-attachment",
+    create: () => workOrderModule,
+  },
+  // @windy-module work-order end
+];
+
+const projectAttachments: readonly WindyServerModuleAttachment<ProjectBusinessModuleRuntime>[] =
+  [
+    // @windy-module work-order begin
+    {
+      name: "work-order",
+      attach: (runtime) => workOrderModule.attach(runtime),
+    },
+    // @windy-module work-order end
+  ];
+
+/**
+ * 客户拥有的 Server 组合声明。
+ *
+ * 标准 package Adapter 由 Host 动态加载；只有需要客户 Repository 的本地 Adapter
+ * 才在这里覆盖，并通过显式 attachment 获得项目运行时。动态 package 永远不会收到
+ * 数据库或平台内部 Repository。
+ */
+export const serverCompositionDeclaration = defineWindyServerComposition({
+  assembly: moduleAssembly,
+  adapters: projectAdapters,
+  attachments: projectAttachments,
+});

package/template/apps/server/src/application-services.ts

@@ -219,6 +219,8 @@ export async function createApplicationServices(
       : new InMemorySchedulerRepository(),
     taskDefinitions,
     runtime: input.runtime,
+    resolveActor: (actorId) =>
+      resolveCurrentSystemActor(input.systemRepositories, actorId),
     // @windy-module system.workflow begin
     workflow,
     // @windy-module system.workflow end

package/template/apps/server/src/bulk-data/service.ts

@@ -28,6 +28,10 @@ import type {
 } from "./types.js";
 export * from "./input-validation.js";
 
+export type BulkResumeAuthorization = (
+  job: BulkDataJob,
+) => Promise<string | undefined>;
+
 export class BulkDataService {
   private readonly handlers = new Map<string, BulkResourceHandler>();
   private readonly limits: BulkDataLimits;
@@ -40,6 +44,7 @@ export class BulkDataService {
     private readonly now: () => Date = () => new Date(),
     blobStore?: BlobStore,
     private readonly durable?: LegacyDurableAdapter,
+    private readonly authorizeResume?: BulkResumeAuthorization,
   ) {
     this.limits = { ...defaultBulkDataLimits, ...limits };
     this.artifacts = new BulkArtifactStore(repository, blobStore);
@@ -155,6 +160,15 @@ export class BulkDataService {
     if (!job || job.status !== "running" || job.attempt !== generation) {
       return;
     }
+    const denial = this.authorizeResume
+      ? await this.authorizeResume(job)
+      : this.durable
+        ? "resume-authorization-unavailable"
+        : undefined;
+    if (denial) {
+      await this.repository.retryOrFail(job.id, denial, this.now());
+      return;
+    }
     await this.processClaimed(job);
   }
 

package/template/apps/server/src/data-governance/export/authorization-port.ts

@@ -77,7 +77,7 @@ export class SystemGovernedExportAuthorization implements GovernedExportAuthoriz
             key: request.policyKey,
             resourceType: request.resourceType,
             version: request.policyVersion,
-            featureKey: featureKey("system.rbac"),
+            featureKey: featureKey("system.user"),
             exportPermissionKey: "system.user.export",
           }
         : undefined;

package/template/apps/server/src/data-governance/export/postgres-api-fixture.ts

@@ -14,7 +14,11 @@ import { DrizzleDurableJobRepository } from "../../jobs/drizzle-repository.js";
 import { DurableJobService } from "../../jobs/service.js";
 import { DurableJobWorker } from "../../jobs/worker.js";
 import { createPlatformObservability } from "../../observability/bootstrap.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import {
+  createServerRuntime,
+  type AuditEventWriter,
+  type ServerRuntimeOptions,
+} from "../../runtime.js";
 import { identityRouteConfigs } from "../../system/identity-route-config.js";
 import { registerSystemRoutes } from "../../system/routes.js";
 import { createSystemRepositories } from "../../system/seed.js";
@@ -67,7 +71,7 @@ export async function createPostgresApiFixture(
   const actors = governanceActors();
   const actorResolver = bearerActorResolver(actors);
   const logs: Array<Record<string, unknown>> = [];
-  const runtime = createServerRuntime({}, { actorResolver, auditWriter });
+  const runtime = createGovernanceRuntime({ actorResolver, auditWriter });
   const stack = createGovernanceStack({
     db,
     runtime,
@@ -94,6 +98,18 @@ export async function createPostgresApiFixture(
   };
 }
 
+export function createGovernanceRuntime(
+  options: Pick<ServerRuntimeOptions, "actorResolver" | "auditWriter">,
+) {
+  return createServerRuntime(
+    {},
+    {
+      ...options,
+      featureCatalog: createFoundationSnapshot().features,
+    },
+  );
+}
+
 export function createGovernanceStack(input: {
   db: NodePgDatabase;
   runtime: ReturnType<typeof createServerRuntime>;

package/template/apps/server/src/data-governance/export/postgres-recovery.integration.test.ts

@@ -5,7 +5,7 @@ import { Pool } from "pg";
 import { FileAuditRecoveryQueue } from "../../audit/recovery-queue.js";
 import { ReliableAuditWriter } from "../../audit/reliable-writer.js";
 import { DrizzleAuditLogWriter } from "../../audit/drizzle-log-store.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import type { AuditEventWriter } from "../../runtime.js";
 import {
   assertNoCanaries,
   createExport,
@@ -17,6 +17,7 @@ import {
 import {
   apiRequest,
   approveExport,
+  createGovernanceRuntime,
   createGovernanceStack,
   createPostgresApiFixture,
   ownerCanaries,
@@ -249,10 +250,10 @@ async function exerciseRecoveryQueue(
     join(fixture.storageRoot, "audit-recovery.json"),
   );
   const reliable = reliableWriter(primary, queue);
-  const runtime = createServerRuntime(
-    {},
-    { actorResolver: fixture.actorResolver, auditWriter: reliable },
-  );
+  const runtime = createGovernanceRuntime({
+    actorResolver: fixture.actorResolver,
+    auditWriter: reliable,
+  });
   const stack = createGovernanceStack({
     db: fixture.db,
     runtime,
@@ -294,10 +295,10 @@ async function exerciseDoubleFault(
       },
     },
   );
-  const runtime = createServerRuntime(
-    {},
-    { actorResolver: fixture.actorResolver, auditWriter: reliable },
-  );
+  const runtime = createGovernanceRuntime({
+    actorResolver: fixture.actorResolver,
+    auditWriter: reliable,
+  });
   const stack = createGovernanceStack({
     db: fixture.db,
     runtime,

package/template/apps/server/src/data-governance/export/routes-test-fixture.ts

@@ -11,7 +11,8 @@ import { DurableArtifactService } from "../../jobs/artifact-service.js";
 import { InMemoryDurableExecutionRepository } from "../../jobs/in-memory-execution.js";
 import { DurableJobService } from "../../jobs/service.js";
 import { DurableJobWorker } from "../../jobs/worker.js";
-import { createServerRuntime, type AuditEventWriter } from "../../runtime.js";
+import type { AuditEventWriter } from "../../runtime.js";
+import { createRouteTestRuntime } from "../../system/route-test-runtime.js";
 import { FakeRouteApp } from "../../system/route-test-app.js";
 import type { GovernedExportApprovalPort } from "./approval-port.js";
 import { GovernedExportJobRuntime } from "./job-runtime.js";
@@ -34,7 +35,9 @@ export async function createFixture(
       await auditWriter?.write(event, policy);
     },
   };
-  const runtime = createServerRuntime(
+  const foundation = createFoundationSnapshot();
+  const runtime = createRouteTestRuntime(
+    foundation,
     { WINDY_DEV_ADMIN_TOKEN: "token" },
     { auditWriter: writer },
   );
@@ -86,12 +89,7 @@ export async function createFixture(
     { approvalRequired: true, retentionSeconds: 3600 },
   );
   const app = new FakeRouteApp();
-  registerGovernedUserExportRoutes(
-    app,
-    service,
-    runtime,
-    createFoundationSnapshot().features,
-  );
+  registerGovernedUserExportRoutes(app, service, runtime, foundation.features);
   return {
     app,
     approval,

package/template/apps/server/src/data-governance/user-plaintext-routes.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createFoundationSnapshot } from "../foundation.js";
-import { createServerRuntime, type AuditEventWriter } from "../runtime.js";
+import type { AuditEventWriter } from "../runtime.js";
+import { createRouteTestRuntime } from "../system/route-test-runtime.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import { registerSystemRoutes } from "../system/routes.js";
 import { createSystemRepositories } from "../system/seed.js";
@@ -249,7 +250,8 @@ describe("用户敏感字段 API", () => {
 async function fixture(auditWriter?: AuditEventWriter) {
   const snapshot = createFoundationSnapshot();
   const repositories = createSystemRepositories(snapshot);
-  const runtime = createServerRuntime(
+  const runtime = createRouteTestRuntime(
+    snapshot,
     { WINDY_DEV_ADMIN_TOKEN: "token" },
     { auditWriter },
   );

package/template/apps/server/src/feature/routes.authorization.test.ts

@@ -95,6 +95,26 @@ describe("Feature Flag 管理授权", () => {
     expect(item).toMatchObject({ key: "system.rbac", enabled: true });
   });
 
+  test("Feature 管理核心能力不能关闭或隐藏", async () => {
+    const fixture = await createFixture(actor(["developer"], true));
+
+    for (const body of [
+      { enabled: false },
+      { visible: "hidden" },
+      { licenseVersionOverride: ["advanced"] },
+    ]) {
+      const response = (await updateFeature(
+        fixture,
+        body,
+        "system.feature",
+      )) as Response;
+      expect(response.status).toBe(409);
+      await expect(response.json()).resolves.toMatchObject({
+        error: "FEATURE_CONTROL_IMMUTABLE",
+      });
+    }
+  });
+
   test("Feature Flag 更新明确使用关键审计策略", async () => {
     const policies: string[] = [];
     const fixture = await createFixture(actor(["developer"], true), {
@@ -166,7 +186,12 @@ async function createFixture(
     },
   );
   const app = new FakeRouteApp();
-  registerFeatureFlagRoutes(app, repositories.features, runtime);
+  registerFeatureFlagRoutes(
+    app,
+    repositories.features,
+    runtime,
+    snapshot.features.find(({ key }) => key === "system.feature")!,
+  );
   const guardContext = await runtime.createGuardContext(
     new Request("http://localhost/api/system/features/system.profile"),
   );

package/template/apps/server/src/feature/routes.ts

@@ -25,21 +25,16 @@ export function registerFeatureFlagRoutes(
   app: RouteApp,
   repository: ManifestFeatureRepository,
   runtime: ServerRuntime,
+  feature: FeatureFlagDefinition,
 ) {
   app.get("/system/features", async (rawContext) => {
     const { guardContext, query } = routeContext(rawContext);
-    return withFeaturePermission(
-      runtime,
-      guardContext,
-      "read",
-      undefined,
-      () => {
-        const listQuery = parseListQuery(query);
-        return listQuery instanceof Response
-          ? listQuery
-          : repository.list(listQuery, ["key", "label", "module"]);
-      },
-    );
+    return withFeaturePermission(runtime, guardContext, "read", feature, () => {
+      const listQuery = parseListQuery(query);
+      return listQuery instanceof Response
+        ? listQuery
+        : repository.list(listQuery, ["key", "label", "module"]);
+    });
   });
 
   app.get("/system/features/export", async (rawContext) => {
@@ -48,7 +43,7 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "read",
-      undefined,
+      feature,
       async () => {
         const listQuery = parseListQuery(query);
         if (listQuery instanceof Response) return listQuery;
@@ -78,7 +73,7 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "read",
-      undefined,
+      feature,
       async () => {
         const id = requiredId(params);
         return (await repository.get(id)) || notFound("features", id);
@@ -92,11 +87,21 @@ export function registerFeatureFlagRoutes(
       runtime,
       guardContext,
       "manage",
-      undefined,
+      feature,
       async () => {
         const id = requiredId(params);
         const input = readStatePatch(body);
         if (input instanceof Response) return input;
+        if (id === feature.key && wouldDisableFeatureControl(input)) {
+          return Response.json(
+            {
+              error: "FEATURE_CONTROL_IMMUTABLE",
+              message:
+                "功能开关管理是核心恢复能力，不能关闭、隐藏或限制 License。",
+            },
+            { status: 409 },
+          );
+        }
         const item = await repository.updateState(
           id,
           input,
@@ -156,6 +161,19 @@ function readStatePatch(
   };
 }
 
+function wouldDisableFeatureControl(
+  input: Partial<
+    Pick<ManagedFeature, "enabled" | "visible" | "licenseVersionOverride">
+  >,
+): boolean {
+  return (
+    input.enabled === false ||
+    input.visible === "hidden" ||
+    (input.licenseVersionOverride !== undefined &&
+      input.licenseVersionOverride !== null)
+  );
+}
+
 function readLicenseVersionOverride(
   record: Record<string, unknown>,
 ): LicenseVersionKey[] | null | undefined | Response {

package/template/apps/server/src/foundation-activation.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import {
+  // @windy-module system.settings begin
+  composeModuleMenus,
+  validateModuleComposition,
+  // @windy-module system.settings end
+  systemModuleManifests,
+} from "@southwind-ai/modules";
+import { applyPlatformModuleActivation } from "./foundation.js";
+
+describe("平台 Module 运行时启停", () => {
+  // @windy-module system.operations begin
+  test("停用只关闭能力与入口，保留静态实现声明用于一致性校验", () => {
+    const source = systemModuleManifests().find(
+      ({ name }) => name === "system.operations",
+    )!;
+    const disabled = applyPlatformModuleActivation(source, false);
+
+    expect(disabled.features.every(({ enabled }) => !enabled)).toBe(true);
+    expect(disabled.features.every(({ visible }) => visible === "hidden")).toBe(
+      true,
+    );
+    expect(
+      disabled.menus
+        .flatMap(({ children }) => children ?? [])
+        .every(({ visible }) => !visible),
+    ).toBe(true);
+    expect(
+      disabled.menus
+        .filter(({ type }) => type === "catalog")
+        .every(({ visible }) => visible),
+    ).toBe(true);
+    expect(disabled.apiPermissions).toEqual(source.apiPermissions);
+    expect(disabled.adminRoutes).toEqual(source.adminRoutes);
+  });
+  // @windy-module system.operations end
+
+  // @windy-module system.settings begin
+  test("停用一个平台 Module 不改变共享菜单目录壳", () => {
+    const modules = systemModuleManifests().map((manifest) =>
+      applyPlatformModuleActivation(
+        manifest,
+        manifest.name !== "system.settings",
+      ),
+    );
+
+    expect(() => validateModuleComposition(modules)).not.toThrow();
+    expect(
+      composeModuleMenus(modules)
+        .find(({ key }) => key === "system.configuration")
+        ?.children?.find(({ key }) => key === "system.settings")?.visible,
+    ).toBe(false);
+  });
+  // @windy-module system.settings end
+
+  test("启用时保留原始 Manifest 身份", () => {
+    const source = systemModuleManifests()[0]!;
+    expect(applyPlatformModuleActivation(source, true)).toBe(source);
+  });
+});