create-windy 0.8.3 → 0.9.1

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

@@ -1,3 +1,6 @@
+// @windy-module system.audit begin
+import { createDiagnosticFailureRecorder } from "./observability/diagnostic-failure-recorder.js";
+// @windy-module system.audit end
 import { swagger } from "@elysiajs/swagger";
 import { Elysia } from "elysia";
 import type { RequestGuardContext } from "./guards.js";
@@ -19,6 +22,9 @@ export function createPlatformHttpApp(
   runtime: ServerRuntime,
   observability: PlatformObservability,
 ) {
+  // @windy-module system.audit begin
+  const failures = createDiagnosticFailureRecorder(observability.diagnostics);
+  // @windy-module system.audit end
   const requestStates = new WeakMap<Request, HttpRequestState>();
   return (
     new Elysia({ prefix: "/api" })
@@ -53,6 +59,31 @@ export function createPlatformHttpApp(
         restrictedRequestResponse(runtime, guardContext, request),
       )
       // @windy-module system.license end
+      // @windy-module system.audit begin
+      .mapResponse(async ({ request, responseValue, set, route }) => {
+        const state = requestStates.get(request);
+        if (!state) return;
+        const receipt = await failures.capture({
+          request,
+          requestId: state.guardContext.requestId,
+          route,
+          responseValue,
+          status: set.status,
+        });
+        if (receipt) {
+          set.headers["x-diagnostic-id"] = receipt.diagnosticId;
+          if (responseValue instanceof Response) {
+            const headers = new Headers(responseValue.headers);
+            headers.set("x-diagnostic-id", receipt.diagnosticId);
+            return new Response(responseValue.body, {
+              status: responseValue.status,
+              statusText: responseValue.statusText,
+              headers,
+            });
+          }
+        }
+      })
+      // @windy-module system.audit end
       .onAfterResponse(({ request, responseValue, set }) => {
         const state = requestStates.get(request);
         if (!state) return;

package/template/apps/server/src/mcp/adapter.ts

@@ -144,6 +144,7 @@ function toMcpTool(tool: RegisteredTool): Tool {
     title: tool.label,
     description: tool.description,
     inputSchema: toMcpSchema(tool.inputSchema),
+    _meta: { "windy/moduleKey": tool.module },
     outputSchema: toMcpSchema(tool.outputSchema),
     annotations: {
       title: tool.label,

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",

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

@@ -38,13 +38,20 @@ 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 ?? [],
   );
   validateModuleComposition(input.modules, {
-    apiRoutes: input.routes.map(apiRouteKey),
+    apiRoutes,
     tasks: (input.tasks || []).map(({ key }) => key),
     tools: [...(input.tools?.keys() || [])],
     aiOperations: input.aiOperations,

package/template/apps/server/src/observability/bootstrap.ts

@@ -1,3 +1,9 @@
+// @windy-module system.audit begin
+import {
+  createDiagnosticIndex,
+  type DiagnosticIndex,
+} from "./diagnostic-index.js";
+// @windy-module system.audit end
 import type { AuditWriteStatus } from "../audit/contracts.js";
 import type { FeatureManifestSyncResult } from "../feature/manifest-feature-repository.js";
 import type { RouteApp } from "../system/route-types.js";
@@ -12,6 +18,9 @@ import { registerObservabilityRoutes } from "./routes.js";
 export interface PlatformObservabilityOptions {
   databaseCheck?: () => Promise<void>;
   databaseRequired: boolean;
+  // @windy-module system.audit begin
+  diagnosticIndex?: DiagnosticIndex;
+  // @windy-module system.audit end
   auditStatus(): AuditWriteStatus;
   logger: StructuredRequestLogger;
 }
@@ -25,6 +34,9 @@ export function createPlatformObservability(
   return {
     http,
     metrics,
+    // @windy-module system.audit begin
+    diagnostics: options.diagnosticIndex ?? createDiagnosticIndex(),
+    // @windy-module system.audit end
     register(app: Pick<RouteApp, "get">) {
       registerObservabilityRoutes(app, readiness, metrics);
     },

package/template/apps/server/src/observability/diagnostic-failure-recorder.ts

@@ -0,0 +1,94 @@
+import { responseStatus } from "./http-observability.js";
+import {
+  diagnosticRecord,
+  newDiagnosticId,
+  safeDiagnosticCode,
+  type DiagnosticIndex,
+} from "./diagnostic-index.js";
+
+export interface DiagnosticFailureInput {
+  readonly request: Request;
+  /** 必须来自路由注册表，禁止传入请求 URL 或包含真实参数的 pathname。 */
+  readonly route?: string;
+  readonly requestId: string;
+  readonly responseValue: unknown;
+  readonly status?: number | string;
+  readonly errorCode?: unknown;
+}
+
+export interface DiagnosticFailureReceipt {
+  readonly diagnosticId: string;
+  readonly errorCode: string;
+  readonly persisted: boolean;
+}
+
+export function createDiagnosticFailureRecorder(index: DiagnosticIndex) {
+  const captured = new WeakMap<
+    Request,
+    Promise<DiagnosticFailureReceipt | undefined>
+  >();
+  let nextPurge = 0;
+  return {
+    capture(
+      input: DiagnosticFailureInput,
+    ): Promise<DiagnosticFailureReceipt | undefined> {
+      const previous = captured.get(input.request);
+      if (previous) return previous;
+      const pending = record(input);
+      captured.set(input.request, pending);
+      return pending;
+    },
+  };
+
+  async function record(
+    input: DiagnosticFailureInput,
+  ): Promise<DiagnosticFailureReceipt | undefined> {
+    const statusCode = responseStatus(input.responseValue, input.status);
+    if (statusCode < 400) return;
+    const diagnosticId = newDiagnosticId();
+    const suppliedCode = input.errorCode ?? objectError(input.responseValue);
+    const errorCode = safeDiagnosticCode(suppliedCode, statusCode);
+    const record = diagnosticRecord({
+      diagnosticId,
+      requestId: /^[A-Za-z0-9._:-]{1,160}$/.test(input.requestId)
+        ? input.requestId
+        : "(unavailable)",
+      service: "server",
+      stage: "http",
+      method: /^(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS)$/.test(
+        input.request.method,
+      )
+        ? input.request.method
+        : "OTHER",
+      route: safeDiagnosticRoute(input.route),
+      statusCode,
+      errorCode,
+    });
+    try {
+      await index.record(record);
+      if (Date.now() >= nextPurge) {
+        nextPurge = Date.now() + 60_000;
+        // 有界批量清理不影响失败响应和原始错误处理。
+        void index.purgeExpired().catch(() => {});
+      }
+      return { diagnosticId, errorCode, persisted: true };
+    } catch {
+      return { diagnosticId, errorCode, persisted: false };
+    }
+  }
+}
+
+export function safeDiagnosticRoute(route: unknown): string {
+  return typeof route === "string" && /^\/[A-Za-z0-9_./:*-]{0,255}$/.test(route)
+    ? route
+    : "(unmatched)";
+}
+
+function objectError(value: unknown): unknown {
+  return value &&
+    typeof value === "object" &&
+    !(value instanceof Response) &&
+    "error" in value
+    ? value.error
+    : undefined;
+}

package/template/apps/server/src/observability/diagnostic-http-contract.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { createPlatformHttpApp } from "../http-app.js";
+import { createServerRuntime } from "../runtime.js";
+import { createPlatformObservability } from "./bootstrap.js";
+
+test("实际 HTTP 失败响应带诊断编号并只持久化模板与脱敏摘要", async () => {
+  const observability = createPlatformObservability({
+    databaseRequired: false,
+    auditStatus: () => ({
+      queued: 0,
+      dropped: 0,
+      state: "healthy",
+      attempted: 0,
+      persisted: 0,
+      failedAttempts: 0,
+      retries: 0,
+    }),
+    logger: { info() {} },
+  });
+  const app = createPlatformHttpApp(createServerRuntime(), observability).get(
+    "/synthetic/:privateId",
+    () =>
+      Response.json(
+        { error: "SAFE_FAILURE", privateBody: "private-note" },
+        { status: 503 },
+      ),
+  );
+  const response = await app.handle(
+    new Request("http://localhost/api/synthetic/secret-id?secret=query"),
+  );
+  expect(response.status).toBe(503);
+  const id = response.headers.get("x-diagnostic-id");
+  expect(id).toMatch(/^diag-/);
+  const record = await observability.diagnostics.find(id!);
+  expect(record).toMatchObject({
+    route: "/api/synthetic/:privateId",
+    statusCode: 503,
+  });
+  const serialized = JSON.stringify(record);
+  for (const secret of ["secret-id", "private-note", "secret=query"])
+    expect(serialized).not.toContain(secret);
+});

package/template/apps/server/src/observability/diagnostic-index.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { createDiagnosticFailureRecorder } from "./diagnostic-failure-recorder.js";
+import {
+  InMemoryDiagnosticIndex,
+  newDiagnosticId,
+  validDiagnosticId,
+} from "./diagnostic-index.js";
+
+describe("受控失败索引", () => {
+  test("同一请求只记录一次，不持久化 URL 查询、正文或错误内容", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    const request = new Request(
+      "https://example.test/api/people/private-id?token=secret",
+      { method: "POST", body: "private material" },
+    );
+    const input = {
+      request,
+      route: "/api/people/:id",
+      requestId: "safe-request",
+      status: 500,
+      responseValue: { error: "Provider returned secret body" },
+    };
+    const [first, second] = await Promise.all([
+      recorder.capture(input),
+      recorder.capture(input),
+    ]);
+    expect(first).toEqual(second);
+    expect(validDiagnosticId(first!.diagnosticId)).toBe(true);
+    const stored = await index.find(first!.diagnosticId);
+    expect(stored).toMatchObject({
+      route: "/api/people/:id",
+      errorCode: "UNEXPECTED_FAILURE",
+      requestId: "safe-request",
+      statusCode: 500,
+    });
+    const serialized = JSON.stringify(stored);
+    for (const secret of [
+      "private-id",
+      "token",
+      "secret",
+      "private material",
+      "Provider",
+    ])
+      expect(serialized).not.toContain(secret);
+  });
+
+  test("成功请求不产生索引，失效清理使用相同30天边界", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    const recorder = createDiagnosticFailureRecorder(index);
+    expect(
+      await recorder.capture({
+        request: new Request("https://test.invalid/"),
+        requestId: "ok",
+        responseValue: new Response(null, { status: 200 }),
+      }),
+    ).toBeUndefined();
+    const receipt = await recorder.capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: new Response(null, { status: 503 }),
+    });
+    const stored = await index.find(receipt!.diagnosticId);
+    const expiry = new Date(stored!.expiresAt);
+    expect(
+      await index.find(receipt!.diagnosticId, new Date(expiry.getTime() - 1)),
+    ).toBeDefined();
+    expect(await index.find(receipt!.diagnosticId, expiry)).toBeUndefined();
+    expect(await index.purgeExpired(expiry)).toBe(1);
+  });
+
+  test("索引失败不掩盖原请求失败，返回受控关联回执", async () => {
+    const index = new InMemoryDiagnosticIndex();
+    index.record = async () => {
+      throw new Error("storage secret");
+    };
+    const receipt = await createDiagnosticFailureRecorder(index).capture({
+      request: new Request("https://test.invalid/"),
+      requestId: "failed",
+      responseValue: { error: "OPERATION_DENIED" },
+      status: 403,
+    });
+    expect(receipt).toMatchObject({
+      errorCode: "OPERATION_DENIED",
+      persisted: false,
+    });
+    expect(validDiagnosticId(newDiagnosticId())).toBe(true);
+  });
+});

package/template/apps/server/src/observability/diagnostic-index.ts

@@ -0,0 +1,88 @@
+import { randomUUIDv7 } from "bun";
+import type { DiagnosticRecord } from "@southwind-ai/shared";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { DrizzleDiagnosticIndex } from "./diagnostic-repository.js";
+
+export type { DiagnosticRecord } from "@southwind-ai/shared";
+export const DIAGNOSTIC_RETENTION_DAYS = 30;
+const RETENTION_MS = DIAGNOSTIC_RETENTION_DAYS * 86_400_000;
+const ID_PATTERN =
+  /^diag-([0-9a-f]{8})-([0-9a-f]{4})-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+export interface DiagnosticIndex {
+  record(record: DiagnosticRecord): Promise<void>;
+  find(id: string, now?: Date): Promise<DiagnosticRecord | undefined>;
+  purgeExpired(now?: Date): Promise<number>;
+}
+
+export function createDiagnosticIndex(db?: NodePgDatabase): DiagnosticIndex {
+  return db ? new DrizzleDiagnosticIndex(db) : new InMemoryDiagnosticIndex();
+}
+
+export function newDiagnosticId(): string {
+  return `diag-${randomUUIDv7()}`;
+}
+
+export function validDiagnosticId(id: string): boolean {
+  return ID_PATTERN.test(id);
+}
+
+export function expiredDiagnosticId(id: string, now = new Date()): boolean {
+  const match = ID_PATTERN.exec(id);
+  return Boolean(
+    match &&
+    Number.parseInt(`${match[1]}${match[2]}`, 16) + RETENTION_MS <=
+      now.getTime(),
+  );
+}
+
+export function safeDiagnosticCode(value: unknown, statusCode: number): string {
+  return typeof value === "string" && /^[A-Z][A-Z0-9_]{1,79}$/.test(value)
+    ? value
+    : statusCode >= 500
+      ? "UNEXPECTED_FAILURE"
+      : `HTTP_${statusCode}`;
+}
+
+export function diagnosticRecord(
+  input: Omit<DiagnosticRecord, "occurredAt" | "expiresAt">,
+  now = new Date(),
+): DiagnosticRecord {
+  return {
+    ...input,
+    occurredAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + RETENTION_MS).toISOString(),
+  };
+}
+
+/** 无数据库开发模式有界保存；正式部署使用相同接口的 Drizzle Repository。 */
+export class InMemoryDiagnosticIndex implements DiagnosticIndex {
+  private readonly items = new Map<string, DiagnosticRecord>();
+  constructor(private readonly maxItems = 10_000) {}
+
+  async record(record: DiagnosticRecord): Promise<void> {
+    this.items.set(record.diagnosticId, structuredClone(record));
+    if (this.items.size > this.maxItems)
+      this.items.delete(this.items.keys().next().value!);
+  }
+
+  async find(
+    id: string,
+    now = new Date(),
+  ): Promise<DiagnosticRecord | undefined> {
+    const item = validDiagnosticId(id) ? this.items.get(id) : undefined;
+    return item && new Date(item.expiresAt) > now
+      ? structuredClone(item)
+      : undefined;
+  }
+
+  async purgeExpired(now = new Date()): Promise<number> {
+    let count = 0;
+    for (const [id, item] of this.items) {
+      if (new Date(item.expiresAt) > now) continue;
+      this.items.delete(id);
+      count++;
+    }
+    return count;
+  }
+}

package/template/apps/server/src/observability/diagnostic-repository.ts

@@ -0,0 +1,67 @@
+import { and, eq, gt, inArray, lte } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { diagnosticEvents } from "@southwind-ai/database";
+import type { DiagnosticRecord } from "@southwind-ai/shared";
+import type { DiagnosticIndex } from "./diagnostic-index.js";
+
+export class DrizzleDiagnosticIndex implements DiagnosticIndex {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async record(record: DiagnosticRecord): Promise<void> {
+    await this.db
+      .insert(diagnosticEvents)
+      .values({
+        ...record,
+        occurredAt: new Date(record.occurredAt),
+        expiresAt: new Date(record.expiresAt),
+      })
+      .onConflictDoNothing();
+  }
+
+  async find(
+    id: string,
+    now = new Date(),
+  ): Promise<DiagnosticRecord | undefined> {
+    const [row] = await this.db
+      .select()
+      .from(diagnosticEvents)
+      .where(
+        and(
+          eq(diagnosticEvents.diagnosticId, id),
+          gt(diagnosticEvents.expiresAt, now),
+        ),
+      )
+      .limit(1);
+    return row
+      ? {
+          ...row,
+          service: "server",
+          stage: "http",
+          occurredAt: row.occurredAt.toISOString(),
+          expiresAt: row.expiresAt.toISOString(),
+        }
+      : undefined;
+  }
+
+  async purgeExpired(now = new Date()): Promise<number> {
+    const expired = await this.db
+      .select({ id: diagnosticEvents.diagnosticId })
+      .from(diagnosticEvents)
+      .where(lte(diagnosticEvents.expiresAt, now))
+      .limit(5_000);
+    if (!expired.length) return 0;
+    const removed = await this.db
+      .delete(diagnosticEvents)
+      .where(
+        and(
+          inArray(
+            diagnosticEvents.diagnosticId,
+            expired.map(({ id }) => id),
+          ),
+          lte(diagnosticEvents.expiresAt, now),
+        ),
+      )
+      .returning({ id: diagnosticEvents.diagnosticId });
+    return removed.length;
+  }
+}

package/template/apps/server/src/platform-app-bootstrap.ts

@@ -1,3 +1,11 @@
+// @windy-module system.agent begin
+import { prepareAgentGovernance } from "./agent/governance-runtime.js";
+import { registerAgentSkillRoutes } from "./agent-skills/bootstrap.js";
+import { registerDshWorkbenchRoutes } from "./app/dsh-workbench.js";
+// @windy-module system.agent end
+// @windy-module system.audit begin
+import { registerDiagnosticRoutes } from "./system/diagnostic-routes.js";
+// @windy-module system.audit end
 import type { ModuleManifest } from "@southwind-ai/modules";
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import type { AuthRepository } from "./auth/repository.js";
@@ -35,6 +43,15 @@ interface PlatformAppBootstrapInput extends Omit<
 
 export async function bootstrapPlatformApp(input: PlatformAppBootstrapInput) {
   const app = await createPlatformServerApp(input);
+  // @windy-module system.audit begin
+  if (input.modules.some((module) => module.name === "system.audit"))
+    registerDiagnosticRoutes(
+      app,
+      input.runtime,
+      input.features,
+      input.observability.diagnostics,
+    );
+  // @windy-module system.audit end
   const authorizer = createStaticRouteAuthorizer(input.runtime, input.modules);
   // @windy-module system.license begin
   registerPlatformLicenseRoutes(app, input.licenseRuntime, authorizer);
@@ -46,5 +63,30 @@ export async function bootstrapPlatformApp(input: PlatformAppBootstrapInput) {
     input.runtime,
     input.features,
   );
+  // @windy-module system.agent begin
+  if (input.modules.some((module) => module.name === "system.agent")) {
+    const governance = await prepareAgentGovernance({
+      runtime: input.runtime,
+      modules: input.modules,
+      db: input.persistence?.db,
+    });
+    registerAgentSkillRoutes(
+      createManifestAuthorizedRouteApp(app, authorizer),
+      governance.skills,
+    );
+    registerDshWorkbenchRoutes({
+      app,
+      runtime: input.runtime,
+      modules: input.modules,
+      authRepository: input.authRepository,
+      sessionCookieName: input.platformConfig.security.sessionCookieName,
+      enabled: input.platformConfig.enableAI,
+      options: {
+        publishedSkills: (context) =>
+          governance.skills.publishedBundles(context),
+      },
+    });
+  }
+  // @windy-module system.agent end
   return app;
 }

package/template/apps/server/src/platform-http-runtime.ts

@@ -1,3 +1,6 @@
+// @windy-module system.audit begin
+import { createDiagnosticIndex } from "./observability/diagnostic-index.js";
+// @windy-module system.audit end
 import type { PlatformConfig } from "@southwind-ai/config";
 import type { FeatureFlagDefinition } from "@southwind-ai/shared";
 import type { AuthRepository } from "./auth/repository.js";
@@ -52,6 +55,9 @@ export function createHttpObservability(
     databaseRequired: process.env.NODE_ENV === "production",
     auditStatus: () => runtime.auditSink.status(),
     logger,
+    // @windy-module system.audit begin
+    diagnosticIndex: createDiagnosticIndex(persistence?.db),
+    // @windy-module system.audit end
   });
 }
 

package/template/apps/server/src/runtime-development.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { systemModuleManifests } from "@southwind-ai/modules";
+import { developmentAdminActor } from "./runtime-development.js";
+
+describe("开发Token默认权限", () => {
+  test("随Manifest补充标准能力，不自动授予敏感披露或治理导出", () => {
+    const actor = developmentAdminActor();
+    const permissions = systemModuleManifests().flatMap(
+      (module) => module.permissions,
+    );
+    const standard = permissions.filter(
+      ({ accessRisk }) => !accessRisk || accessRisk === "standard",
+    );
+    const restricted = permissions.filter(
+      ({ accessRisk }) => accessRisk && accessRisk !== "standard",
+    );
+    expect(standard.length).toBeGreaterThan(0);
+    for (const permission of standard)
+      expect(actor.permissionKeys).toContain(permission.key);
+    for (const permission of restricted)
+      expect(actor.permissionKeys).not.toContain(permission.key);
+    expect(actor.permissionKeys).not.toContain("system.user.reveal");
+    expect(actor.permissionKeys).not.toContain("system.user.export");
+  });
+});