create-windy 0.3.16 → 0.3.18

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

@@ -1,4 +1,7 @@
+// @windy-module system.bulk-data begin
 import { DictionaryBulkResourceHandler } from "./bulk-data/dictionary-handler.js";
+// @windy-module system.bulk-data end
+// @windy-module system.data-governance begin
 import { DrizzleGovernedExportRepository } from "./data-governance/export/drizzle-repository.js";
 import { WorkflowGovernedExportApproval } from "./data-governance/export/approval-port.js";
 import { GovernedExportJobRuntime } from "./data-governance/export/job-runtime.js";
@@ -9,25 +12,41 @@ import {
   GovernedUserExportSource,
   ModuleGovernedExportSource,
 } from "./data-governance/export/source.js";
+// @windy-module system.data-governance end
+// @windy-module system.bulk-data begin
 import { DrizzleBulkDataRepository } from "./bulk-data/drizzle-repository.js";
 import { InMemoryBulkDataRepository } from "./bulk-data/repository.js";
+// @windy-module system.bulk-data end
 import type { createFoundationSnapshot } from "./foundation.js";
 import { createLegacyServiceRuntime } from "./jobs/legacy-service-runtime.js";
+// @windy-module system.data-governance begin
 import { DurableArtifactService } from "./jobs/artifact-service.js";
+// @windy-module system.data-governance end
+// @windy-module system.notification begin
 import { DrizzleNotificationRepository } from "./notification/drizzle-repository.js";
 import { InMemoryNotificationRepository } from "./notification/repository.js";
+// @windy-module system.notification end
 import type { createServerPersistence } from "./persistence.js";
 import type { createServerRuntime } from "./runtime.js";
 import { createPlatformTaskDefinitions } from "./scheduler/definitions.js";
 import { DrizzleSchedulerRepository } from "./scheduler/drizzle-repository.js";
 import { InMemorySchedulerRepository } from "./scheduler/repository.js";
 import type { ScheduledTaskDefinition } from "./scheduler/types.js";
+// @windy-module system.storage begin
 import type { createStorageRuntime } from "./storage/runtime.js";
+// @windy-module system.storage end
+// @windy-module system.notification begin
 import type { PlatformConfig } from "@southwind-ai/config";
+// @windy-module system.notification end
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
+// @windy-module system.storage begin
 import { collectActiveBlobRefs } from "./storage/blob-reference-registry.js";
+// @windy-module system.storage end
 import type { createSystemRepositories } from "./system/seed.js";
+// @windy-module system.data-governance begin
 import { identityRouteConfigs } from "./system/identity-route-config.js";
+// @windy-module system.data-governance end
+// @windy-module system.workflow begin
 import { SystemWorkflowAssigneeDirectory } from "./workflow/assignee-directory.js";
 import { DrizzleWorkflowRepository } from "./workflow/drizzle-repository.js";
 import {
@@ -37,6 +56,8 @@ import {
 } from "./workflow/effects.js";
 import { InMemoryWorkflowRepository } from "./workflow/repository.js";
 import { WorkflowService } from "./workflow/service.js";
+// @windy-module system.workflow end
+// @windy-module system.notification begin
 import { NotificationChannelRegistry } from "./notification/channel-adapter.js";
 import { DrizzleNotificationDeliveryRepository } from "./notification/delivery-repository.js";
 import { NotificationDeliveryWorker } from "./notification/delivery-worker.js";
@@ -48,6 +69,7 @@ import {
 import { SystemNotificationRecipientDirectory } from "./notification/recipient-directory.js";
 import { NotificationService } from "./notification/service.js";
 import { SmtpNotificationChannelAdapter } from "./notification/smtp-adapter.js";
+// @windy-module system.notification end
 import type { InitializedModuleHosts } from "./module-host.js";
 import {
   createModuleDurableContextualizer,
@@ -60,10 +82,16 @@ interface ApplicationServicesInput {
   systemRepositories: ReturnType<typeof createSystemRepositories>;
   foundation: ReturnType<typeof createFoundationSnapshot>;
   runtime: ReturnType<typeof createServerRuntime>;
+  // @windy-module system.storage begin
   storage: ReturnType<typeof createStorageRuntime>;
+  // @windy-module system.storage end
   moduleTasks: ScheduledTaskDefinition[];
+  // @windy-module system.bulk-data begin
   bulkRetentionDays: number;
+  // @windy-module system.bulk-data end
+  // @windy-module system.notification begin
   mailConfig?: PlatformConfig["mail"];
+  // @windy-module system.notification end
   installModuleDurableHandlers?: (registry: DurableHandlerRegistry) => void;
   moduleHosts: InitializedModuleHosts;
   // @windy-module system.agent begin
@@ -75,6 +103,7 @@ export async function createApplicationServices(
   input: ApplicationServicesInput,
 ) {
   const { persistence } = input;
+  // @windy-module system.notification begin
   const notifications = persistence
     ? new DrizzleNotificationRepository(persistence.db)
     : new InMemoryNotificationRepository();
@@ -104,6 +133,8 @@ export async function createApplicationServices(
     notificationRecipients,
     notificationChannels,
   );
+  // @windy-module system.notification end
+  // @windy-module system.workflow begin
   const deferredTimeout = new DeferredWorkflowTimeoutScheduler();
   const workflow = new WorkflowService(
     persistence
@@ -116,31 +147,50 @@ export async function createApplicationServices(
       deferredTimeout,
     ),
   );
+  // @windy-module system.workflow end
+  // @windy-module system.data-governance begin
   const governedExportDispatch: {
     runNext?: GovernedExportJobRuntime["runNext"];
   } = {};
+  // @windy-module system.data-governance end
+  // @windy-module system.bulk-data begin
   const bulkRepository = persistence
     ? new DrizzleBulkDataRepository(persistence.db)
     : new InMemoryBulkDataRepository();
+  // @windy-module system.bulk-data end
   const taskDefinitions = [
     ...createPlatformTaskDefinitions(input.foundation.features, {
+      // @windy-module system.bulk-data begin
       bulkDataDispatch: () => services.bulkDataService.processNext(),
       bulkDataCleanup: () => services.bulkDataService.cleanupExpired(),
+      // @windy-module system.bulk-data end
+      // @windy-module system.storage begin
       storageCleanup: async () => {
         const now = new Date();
         const referencedRefs = await collectActiveBlobRefs(
-          [services.durable.facts, bulkRepository],
+          [
+            services.durable.facts,
+            // @windy-module system.bulk-data begin
+            bulkRepository,
+            // @windy-module system.bulk-data end
+          ],
           now,
         );
         return {
           ...(await input.storage.uploads.cleanupExpired(100, referencedRefs)),
         };
       },
+      // @windy-module system.storage end
+      // @windy-module system.workflow begin
       workflowTimeoutDispatch: () => services.workflowTimeout.runNext(),
+      // @windy-module system.workflow end
+      // @windy-module system.data-governance begin
       governedExportDispatch: async () => {
         const result = await governedExportDispatch.runNext?.();
         return { claimed: Boolean(result && result.status !== "idle") };
       },
+      // @windy-module system.data-governance end
+      // @windy-module system.notification begin
       notificationDispatch: async () => {
         const scheduled = await notificationService.dispatchScheduled();
         const delivery = await notificationDeliveryWorker.runNext();
@@ -150,29 +200,36 @@ export async function createApplicationServices(
           delivery,
         };
       },
+      // @windy-module system.notification end
     }),
     ...input.moduleTasks,
   ];
   const services = createLegacyServiceRuntime({
     db: persistence?.db,
+    // @windy-module system.bulk-data begin
     bulkRepository,
     bulkHandlers: [
       new DictionaryBulkResourceHandler(input.systemRepositories.dictionaries),
     ],
     bulkLimits: { retentionDays: input.bulkRetentionDays },
     blobStore: input.storage.blobStore,
+    // @windy-module system.bulk-data end
     schedulerRepository: persistence
       ? new DrizzleSchedulerRepository(persistence.db)
       : new InMemorySchedulerRepository(),
     taskDefinitions,
     runtime: input.runtime,
+    // @windy-module system.workflow begin
     workflow,
+    // @windy-module system.workflow end
     installModuleDurableHandlers: input.installModuleDurableHandlers,
     durableContextualize: createModuleDurableContextualizer({
       hosts: input.moduleHosts,
       runtime: input.runtime,
       features: input.foundation.features,
+      // @windy-module system.storage begin
       storage: input.storage,
+      // @windy-module system.storage end
       // @windy-module system.agent begin
       backgroundAi: input.backgroundAi,
       // @windy-module system.agent end
@@ -180,6 +237,7 @@ export async function createApplicationServices(
         resolveCurrentSystemActor(input.systemRepositories, actorId),
     }),
   });
+  // @windy-module system.data-governance begin
   const governedExportRequests = persistence
     ? new DrizzleGovernedExportRepository(persistence.db)
     : new InMemoryGovernedExportRepository();
@@ -199,20 +257,21 @@ export async function createApplicationServices(
         resolveCurrentSystemActor(input.systemRepositories, actorId),
       );
     });
-  const moduleGovernedExportRenderers = input.moduleHosts.governedResources.flatMap(
-    ({ moduleName, registration }) => {
-      const policy = input.moduleHosts
-        .manifestOf(moduleName)
-        .dataPolicies?.find(({ key }) => key === registration.policyKey);
-      if (!policy) {
-        throw new Error(`模块数据治理策略不存在：${registration.policyKey}`);
-      }
-      return (registration.export?.renderers ?? []).map((renderer) => ({
-        resourceType: policy.resourceType,
-        renderer,
-      }));
-    },
-  );
+  const moduleGovernedExportRenderers =
+    input.moduleHosts.governedResources.flatMap(
+      ({ moduleName, registration }) => {
+        const policy = input.moduleHosts
+          .manifestOf(moduleName)
+          .dataPolicies?.find(({ key }) => key === registration.policyKey);
+        if (!policy) {
+          throw new Error(`模块数据治理策略不存在：${registration.policyKey}`);
+        }
+        return (registration.export?.renderers ?? []).map((renderer) => ({
+          resourceType: policy.resourceType,
+          renderer,
+        }));
+      },
+    );
   const governedExports = new GovernedExportJobRuntime(
     governedExportRequests,
     services.durable.service,
@@ -251,17 +310,26 @@ export async function createApplicationServices(
     { approvalRequired: true, retentionSeconds: 24 * 60 * 60 },
   );
   governedExportDispatch.runNext = () => governedExports.runNext();
+  // @windy-module system.data-governance end
+  // @windy-module system.workflow begin
   deferredTimeout.attach(services.workflowTimeout);
   await services.workflowTimeout.reconcile();
+  // @windy-module system.workflow end
   await services.scheduler.initialize();
   return {
     ...services,
+    // @windy-module system.notification begin
     notifications,
     notificationService,
     notificationDeliveryWorker,
+    // @windy-module system.notification end
+    // @windy-module system.workflow begin
     workflow,
+    // @windy-module system.workflow end
+    // @windy-module system.data-governance begin
     governedExports,
     governedExportService,
     governedExportRequests,
+    // @windy-module system.data-governance end
   };
 }

package/template/apps/server/src/audit/contracts.ts

@@ -1,5 +1,11 @@
 export type AuditWritePolicy = "ordinary" | "critical";
 
+export type AuditRecoveryFailure =
+  | "permission-denied"
+  | "invalid-format"
+  | "io-error"
+  | "unknown";
+
 export interface AuditWriteStatus {
   state: "healthy" | "degraded";
   attempted: number;
@@ -10,6 +16,8 @@ export interface AuditWriteStatus {
   dropped: number;
   lastFailureAt?: string;
   lastSuccessAt?: string;
+  recoveryFailure?: AuditRecoveryFailure;
+  lastRecoveryFailureAt?: string;
   alert?: string;
 }
 

package/template/apps/server/src/audit/recovery-queue.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, stat } from "node:fs/promises";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import type { AuditEvent } from "@southwind-ai/shared";
@@ -39,4 +39,51 @@ describe("FileAuditRecoveryQueue", () => {
       await Array.fromAsync(new Bun.Glob("*.tmp").scan(directory)),
     ).toEqual([]);
   });
+
+  test("合法空队列保持可读", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-empty-"));
+    directories.push(directory);
+    const filePath = join(directory, "recovery.json");
+    const queue = new FileAuditRecoveryQueue(filePath);
+
+    await queue.replace([]);
+
+    await expect(queue.read()).resolves.toEqual([]);
+  });
+
+  test.each([
+    ["缺少 formatVersion", { events: [] }],
+    ["formatVersion 不受支持", { formatVersion: 2, events: [] }],
+    ["缺少 events", { formatVersion: 1 }],
+    ["events 不是数组", { formatVersion: 1, events: { secret: "不应泄露" } }],
+    [
+      "event 结构损坏",
+      {
+        formatVersion: 1,
+        events: [
+          {
+            id: "audit_invalid",
+            action: "auth.login",
+            outcome: "success",
+            actor: { id: "user_1", type: "invalid", name: "用户一" },
+            occurredAt: "2026-07-10T00:00:00.000Z",
+            secret: "不应泄露",
+          },
+        ],
+      },
+    ],
+  ])("%s 时以稳定无敏感内容错误拒绝", async (_, envelope) => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-invalid-"));
+    directories.push(directory);
+    const filePath = join(directory, "recovery.json");
+    await writeFile(filePath, JSON.stringify(envelope), "utf8");
+
+    const error = await new FileAuditRecoveryQueue(filePath)
+      .read()
+      .catch((failure: unknown) => failure);
+
+    expect(error).toBeInstanceOf(SyntaxError);
+    expect((error as Error).message).toBe("审计恢复队列文件格式无效");
+    expect(String(error)).not.toContain("不应泄露");
+  });
 });

package/template/apps/server/src/audit/recovery-queue.ts

@@ -2,6 +2,9 @@ import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import type { AuditEvent } from "@southwind-ai/shared";
 
+const recoveryQueueFormatVersion = 1;
+const invalidRecoveryQueueMessage = "审计恢复队列文件格式无效";
+
 export interface AuditRecoveryQueue {
   read(): Promise<AuditEvent[]>;
   replace(events: AuditEvent[]): Promise<void>;
@@ -17,6 +20,9 @@ export class FileAuditRecoveryQueue implements AuditRecoveryQueue {
       return readEvents(value);
     } catch (error) {
       if (isMissingFile(error)) return [];
+      if (error instanceof SyntaxError) {
+        throw new SyntaxError(invalidRecoveryQueueMessage);
+      }
       throw error;
     }
   }
@@ -26,7 +32,7 @@ export class FileAuditRecoveryQueue implements AuditRecoveryQueue {
     const temporaryPath = `${this.filePath}.${process.pid}.tmp`;
     await writeFile(
       temporaryPath,
-      JSON.stringify({ formatVersion: 1, events }),
+      JSON.stringify({ formatVersion: recoveryQueueFormatVersion, events }),
       { encoding: "utf8", mode: 0o600 },
     );
     await rename(temporaryPath, this.filePath);
@@ -49,9 +55,72 @@ export class MemoryAuditRecoveryQueue implements AuditRecoveryQueue {
 }
 
 function readEvents(value: unknown): AuditEvent[] {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
-  const events = (value as Record<string, unknown>).events;
-  return Array.isArray(events) ? (events as AuditEvent[]) : [];
+  if (
+    !isRecord(value) ||
+    value.formatVersion !== recoveryQueueFormatVersion ||
+    !Array.isArray(value.events) ||
+    !value.events.every(isAuditEvent)
+  ) {
+    throw new SyntaxError(invalidRecoveryQueueMessage);
+  }
+  return value.events;
+}
+
+function isAuditEvent(value: unknown): value is AuditEvent {
+  if (!isRecord(value) || !isRecord(value.actor)) return false;
+  const actor = value.actor;
+  return (
+    typeof value.id === "string" &&
+    typeof value.action === "string" &&
+    (value.outcome === "attempted" ||
+      value.outcome === "success" ||
+      value.outcome === "failure" ||
+      value.outcome === "denied") &&
+    typeof actor.id === "string" &&
+    (actor.type === "user" ||
+      actor.type === "service" ||
+      actor.type === "system") &&
+    typeof actor.name === "string" &&
+    isOptionalStringArray(actor.roleCodes) &&
+    isOptionalString(actor.ip) &&
+    isOptionalString(actor.userAgent) &&
+    isOptionalTarget(value.target) &&
+    isOptionalString(value.module) &&
+    isOptionalString(value.requestId) &&
+    isOptionalString(value.message) &&
+    isOptionalRecord(value.metadata) &&
+    typeof value.occurredAt === "string"
+  );
+}
+
+function isOptionalTarget(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (isRecord(value) &&
+      typeof value.type === "string" &&
+      isOptionalString(value.id) &&
+      isOptionalString(value.label))
+  );
+}
+
+function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+
+function isOptionalStringArray(value: unknown): boolean {
+  return (
+    value === undefined ||
+    (Array.isArray(value) &&
+      value.every((item): item is string => typeof item === "string"))
+  );
+}
+
+function isOptionalRecord(value: unknown): boolean {
+  return value === undefined || isRecord(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function isMissingFile(error: unknown): boolean {

package/template/apps/server/src/audit/reliable-writer.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { AuditEvent } from "@southwind-ai/shared";
-import { MemoryAuditRecoveryQueue } from "./recovery-queue.js";
+import {
+  FileAuditRecoveryQueue,
+  MemoryAuditRecoveryQueue,
+} from "./recovery-queue.js";
 import {
   AuditWriteUnavailableError,
   ReliableAuditWriter,
@@ -127,6 +133,117 @@ describe("ReliableAuditWriter", () => {
     });
   });
 
+  test("恢复队列权限错误时降级启动并记录稳定诊断", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.failure = Object.assign(new Error("sensitive queue path"), {
+      code: "EACCES",
+    });
+    const alerts: string[] = [];
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      queue,
+      {
+        now: () => new Date("2026-07-28T10:00:00.000Z"),
+        onAlert: (status) => alerts.push(status.alert || ""),
+      },
+    );
+
+    await expect(writer.recover()).resolves.toBeUndefined();
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      recoveryFailure: "permission-denied",
+      lastRecoveryFailureAt: "2026-07-28T10:00:00.000Z",
+      alert: "关键审计恢复队列不可用：文件权限不足",
+    });
+    expect(alerts).toEqual(["关键审计恢复队列不可用：文件权限不足"]);
+    expect(JSON.stringify(writer.status())).not.toContain(
+      "sensitive queue path",
+    );
+  });
+
+  test("恢复队列 JSON 损坏时降级启动且不泄露文件内容", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-audit-corrupt-"));
+    const filePath = join(directory, "recovery.json");
+    await writeFile(filePath, '{"secret":"must-not-leak"', "utf8");
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      new FileAuditRecoveryQueue(filePath),
+      { now: () => new Date("2026-07-28T10:01:00.000Z") },
+    );
+
+    try {
+      await expect(writer.recover()).resolves.toBeUndefined();
+
+      expect(writer.status()).toMatchObject({
+        state: "degraded",
+        recoveryFailure: "invalid-format",
+        lastRecoveryFailureAt: "2026-07-28T10:01:00.000Z",
+        alert: "关键审计恢复队列不可用：队列文件格式无效",
+      });
+      expect(JSON.stringify(writer.status())).not.toContain("must-not-leak");
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  test("普通审计落库成功不能清除恢复队列故障", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.events = [{ ...event(), id: "audit_queued" }];
+    queue.failure = Object.assign(new Error("queue unavailable"), {
+      code: "EIO",
+    });
+    const writer = new ReliableAuditWriter(
+      { write: async () => undefined },
+      queue,
+      { now: () => new Date("2026-07-28T10:02:00.000Z") },
+    );
+    await writer.recover();
+
+    await writer.write(event(), "ordinary");
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      persisted: 1,
+      recoveryFailure: "io-error",
+      lastRecoveryFailureAt: "2026-07-28T10:02:00.000Z",
+      alert: "关键审计恢复队列不可用：文件读写失败",
+    });
+
+    queue.failure = undefined;
+    await writer.recover();
+
+    expect(writer.status()).toMatchObject({
+      state: "healthy",
+      persisted: 2,
+      queued: 0,
+    });
+    expect(queue.events).toEqual([]);
+    expect(writer.status().recoveryFailure).toBeUndefined();
+    expect(writer.status().lastRecoveryFailureAt).toBeUndefined();
+    expect(writer.status().alert).toBeUndefined();
+  });
+
+  test("恢复队列重新可写后以关键事件待重放状态替代队列故障", async () => {
+    const queue = new MemoryAuditRecoveryQueue();
+    queue.failure = Object.assign(new Error("queue unavailable"), {
+      code: "EACCES",
+    });
+    const writer = failingWriter(queue);
+    await writer.recover();
+    queue.failure = undefined;
+
+    await writer.write(event(), "critical");
+
+    expect(writer.status()).toMatchObject({
+      state: "degraded",
+      queued: 1,
+      alert: "关键审计已进入可恢复队列",
+    });
+    expect(writer.status().recoveryFailure).toBeUndefined();
+    expect(writer.status().lastRecoveryFailureAt).toBeUndefined();
+  });
+
   test("当前事件已落库但恢复文件故障时只告警且不误报丢弃", async () => {
     const queue = new MemoryAuditRecoveryQueue();
     let databaseAvailable = false;
@@ -152,7 +269,8 @@ describe("ReliableAuditWriter", () => {
       persisted: 1,
       queued: 1,
       dropped: 0,
-      alert: "关键审计恢复队列不可用",
+      recoveryFailure: "unknown",
+      alert: "关键审计恢复队列不可用：未知错误",
     });
   });