create-windy 0.1.0

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

@@ -0,0 +1,105 @@
+interface SchedulerTickObservation {
+  scheduled: number;
+  retried: number;
+  blocked: number;
+  failed: number;
+}
+
+export interface RequestObservation {
+  method: string;
+  startedAtNs: bigint;
+  finished: boolean;
+}
+
+export class RuntimeMetrics {
+  private readonly startedAt = Date.now();
+  private readonly requestCounts = new Map<string, number>();
+  private activeRequests = 0;
+  private requestDurationSeconds = 0;
+  private completedRequests = 0;
+  private schedulerTicks = 0;
+  private readonly schedulerRuns = {
+    scheduled: 0,
+    retried: 0,
+    blocked: 0,
+    failed: 0,
+  };
+
+  beginRequest(method: string): RequestObservation {
+    this.activeRequests += 1;
+    return {
+      method: safeMethod(method),
+      startedAtNs: process.hrtime.bigint(),
+      finished: false,
+    };
+  }
+
+  finishRequest(observation: RequestObservation, statusCode: number): number {
+    if (observation.finished) return 0;
+    observation.finished = true;
+    this.activeRequests = Math.max(0, this.activeRequests - 1);
+    const durationMs =
+      Number(process.hrtime.bigint() - observation.startedAtNs) / 1e6;
+    this.requestDurationSeconds += durationMs / 1_000;
+    this.completedRequests += 1;
+    const statusClass = `${Math.floor(statusCode / 100)}xx`;
+    const key = `${observation.method}|${statusClass}`;
+    this.requestCounts.set(key, (this.requestCounts.get(key) || 0) + 1);
+    return durationMs;
+  }
+
+  observeSchedulerTick(result: SchedulerTickObservation): void {
+    this.schedulerTicks += 1;
+    this.schedulerRuns.scheduled += result.scheduled;
+    this.schedulerRuns.retried += result.retried;
+    this.schedulerRuns.blocked += result.blocked;
+    this.schedulerRuns.failed += result.failed;
+  }
+
+  render(): string {
+    const lines = [
+      "# HELP windy_process_uptime_seconds Process uptime in seconds.",
+      "# TYPE windy_process_uptime_seconds gauge",
+      `windy_process_uptime_seconds ${secondsSince(this.startedAt)}`,
+      "# HELP windy_process_resident_memory_bytes Resident memory in bytes.",
+      "# TYPE windy_process_resident_memory_bytes gauge",
+      `windy_process_resident_memory_bytes ${process.memoryUsage().rss}`,
+      "# HELP windy_http_requests_active Requests currently executing.",
+      "# TYPE windy_http_requests_active gauge",
+      `windy_http_requests_active ${this.activeRequests}`,
+      "# HELP windy_http_requests_total Completed requests by method and status class.",
+      "# TYPE windy_http_requests_total counter",
+      ...[...this.requestCounts.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => requestMetric(key, value)),
+      "# HELP windy_http_request_duration_seconds Request duration without route or identifier labels.",
+      "# TYPE windy_http_request_duration_seconds summary",
+      `windy_http_request_duration_seconds_sum ${this.requestDurationSeconds.toFixed(6)}`,
+      `windy_http_request_duration_seconds_count ${this.completedRequests}`,
+      "# HELP windy_scheduler_ticks_total Completed scheduler polling ticks.",
+      "# TYPE windy_scheduler_ticks_total counter",
+      `windy_scheduler_ticks_total ${this.schedulerTicks}`,
+      "# HELP windy_scheduler_runs_total Scheduler run transitions observed by outcome.",
+      "# TYPE windy_scheduler_runs_total counter",
+      ...Object.entries(this.schedulerRuns).map(
+        ([outcome, value]) =>
+          `windy_scheduler_runs_total{outcome="${outcome}"} ${value}`,
+      ),
+    ];
+    return `${lines.join("\n")}\n`;
+  }
+}
+
+function safeMethod(method: string): string {
+  const normalized = method.toUpperCase();
+  return /^[A-Z]{1,12}$/.test(normalized) ? normalized : "OTHER";
+}
+
+function requestMetric(key: string, value: number): string {
+  const [method, statusClass] = key.split("|");
+  return `windy_http_requests_total{method="${method}",status_class="${statusClass}"} ${value}`;
+}
+
+function secondsSince(startedAt: number): string {
+  return ((Date.now() - startedAt) / 1_000).toFixed(3);
+}

package/template/apps/server/src/observability/readiness.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { createReadinessProbe } from "./readiness.js";
+
+const audit = {
+  state: "healthy" as const,
+  attempted: 0,
+  persisted: 0,
+  failedAttempts: 0,
+  retries: 0,
+  queued: 0,
+  dropped: 0,
+};
+
+describe("readiness probe", () => {
+  test("生产必需数据库不可用时 not-ready 且不回显异常", async () => {
+    const probe = createReadinessProbe({
+      databaseRequired: true,
+      databaseCheck: () => {
+        throw new Error("postgresql://user:secret@db/internal");
+      },
+      auditStatus: () => audit,
+    });
+    const result = await probe();
+    expect(result.status).toBe("not-ready");
+    expect(result.checks.database).toBe("unavailable");
+    expect(JSON.stringify(result)).not.toContain("secret");
+  });
+
+  test("显式开发内存模式可就绪", async () => {
+    const probe = createReadinessProbe({
+      databaseRequired: false,
+      auditStatus: () => audit,
+    });
+    expect((await probe()).status).toBe("ready");
+  });
+});

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

@@ -0,0 +1,43 @@
+import type { AuditWriteStatus } from "../audit/contracts.js";
+
+export interface ReadinessSnapshot {
+  status: "ready" | "not-ready";
+  checks: {
+    database: "healthy" | "not-configured" | "unavailable";
+    audit: AuditWriteStatus["state"];
+  };
+  audit: AuditWriteStatus;
+}
+
+export interface ReadinessProbeOptions {
+  databaseCheck?: () => Promise<void>;
+  databaseRequired: boolean;
+  auditStatus(): AuditWriteStatus;
+}
+
+export function createReadinessProbe(options: ReadinessProbeOptions) {
+  return async (): Promise<ReadinessSnapshot> => {
+    const database = await databaseStatus(options.databaseCheck);
+    const audit = options.auditStatus();
+    const ready =
+      database === "healthy" ||
+      (!options.databaseRequired && database === "not-configured");
+    return {
+      status: ready ? "ready" : "not-ready",
+      checks: { database, audit: audit.state },
+      audit,
+    };
+  };
+}
+
+async function databaseStatus(
+  check?: () => Promise<void>,
+): Promise<ReadinessSnapshot["checks"]["database"]> {
+  if (!check) return "not-configured";
+  try {
+    await check();
+    return "healthy";
+  } catch {
+    return "unavailable";
+  }
+}

package/template/apps/server/src/observability/routes.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import { RuntimeMetrics } from "./metrics.js";
+import { registerObservabilityRoutes } from "./routes.js";
+
+class FakeApp implements Pick<RouteApp, "get"> {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+  get(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(path, handler);
+  }
+  invoke(path: string): unknown {
+    const handler = this.handlers.get(path);
+    if (!handler) throw new Error(`missing ${path}`);
+    return handler({});
+  }
+}
+
+const audit = {
+  state: "healthy" as const,
+  attempted: 0,
+  persisted: 0,
+  failedAttempts: 0,
+  retries: 0,
+  queued: 0,
+  dropped: 0,
+};
+
+describe("observability routes", () => {
+  test("liveness 不依赖 readiness，readiness 失败返回 503", async () => {
+    const app = new FakeApp();
+    registerObservabilityRoutes(
+      app,
+      async () => ({
+        status: "not-ready",
+        checks: { database: "unavailable", audit: "healthy" },
+        audit,
+      }),
+      new RuntimeMetrics(),
+    );
+    expect((app.invoke("/live") as Response).status).toBe(200);
+    expect(((await app.invoke("/ready")) as Response).status).toBe(503);
+    expect(((await app.invoke("/health")) as Response).status).toBe(503);
+  });
+
+  test("metrics 使用 Prometheus 文本且禁止缓存", async () => {
+    const app = new FakeApp();
+    registerObservabilityRoutes(
+      app,
+      async () => ({
+        status: "ready",
+        checks: { database: "healthy", audit: "healthy" },
+        audit,
+      }),
+      new RuntimeMetrics(),
+    );
+    const response = app.invoke("/metrics") as Response;
+    expect(response.headers.get("content-type")).toContain("text/plain");
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    expect(await response.text()).toContain("windy_process_uptime_seconds");
+  });
+});

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

@@ -0,0 +1,44 @@
+import type { RouteApp } from "../system/route-types.js";
+import type { RuntimeMetrics } from "./metrics.js";
+import type { ReadinessSnapshot } from "./readiness.js";
+
+export function registerObservabilityRoutes(
+  app: Pick<RouteApp, "get">,
+  readiness: () => Promise<ReadinessSnapshot>,
+  metrics: RuntimeMetrics,
+): void {
+  app.get("/live", () => json({ status: "alive" }, 200));
+  app.get("/ready", async () => readinessResponse(await readiness()));
+  app.get("/health", async () => {
+    const snapshot = await readiness();
+    return json(
+      {
+        ...snapshot,
+        status: snapshot.status === "ready" ? "ok" : "not-ready",
+      },
+      snapshot.status === "ready" ? 200 : 503,
+    );
+  });
+  app.get(
+    "/metrics",
+    () =>
+      new Response(metrics.render(), {
+        status: 200,
+        headers: {
+          "cache-control": "no-store",
+          "content-type": "text/plain; version=0.0.4; charset=utf-8",
+        },
+      }),
+  );
+}
+
+function readinessResponse(snapshot: ReadinessSnapshot): Response {
+  return json(snapshot, snapshot.status === "ready" ? 200 : 503);
+}
+
+function json(body: unknown, status: number): Response {
+  return Response.json(body, {
+    status,
+    headers: { "cache-control": "no-store" },
+  });
+}

package/template/apps/server/src/pagination.ts

@@ -0,0 +1,31 @@
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  type PageRequest,
+} from "@windy/shared";
+
+export function parsePagination(query: {
+  page?: string;
+  pageSize?: string;
+}): PageRequest | Response {
+  const page = positiveInteger(query.page, 1);
+  const pageSize = positiveInteger(query.pageSize, DEFAULT_PAGE_SIZE);
+  if (!page || !pageSize || pageSize > MAX_PAGE_SIZE) {
+    return Response.json(
+      {
+        error: "INVALID_PAGINATION",
+        message: `page 必须为正整数；pageSize 必须为 1-${MAX_PAGE_SIZE} 的整数`,
+        maxPageSize: MAX_PAGE_SIZE,
+      },
+      { status: 400 },
+    );
+  }
+  return { page, pageSize };
+}
+
+function positiveInteger(value: string | undefined, fallback: number) {
+  if (value === undefined || value === "") return fallback;
+  if (!/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}

package/template/apps/server/src/persistence.integration.test.ts

@@ -0,0 +1,54 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { AuditEvent } from "@windy/shared";
+import { resolve } from "node:path";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { DrizzleAuditLogWriter } from "./audit/drizzle-log-store.js";
+
+const databaseUrl = process.env.AUDIT_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+
+describePostgres("PostgreSQL audit writer", () => {
+  let pool: Pool;
+  let writer: DrizzleAuditLogWriter;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const db = drizzle(pool);
+    await migrate(db, {
+      migrationsFolder: resolve(
+        import.meta.dir,
+        "../../../packages/database/drizzle",
+      ),
+      migrationsSchema: "public",
+      migrationsTable: "__audit01_test_migrations",
+    });
+    writer = new DrizzleAuditLogWriter(db);
+  });
+
+  afterAll(async () => {
+    await pool?.query("delete from audit_logs where id = 'audit_pg_1'");
+    await pool?.end();
+  });
+
+  test("相同事件恢复重放时按 ID 幂等落库", async () => {
+    const event: AuditEvent = {
+      id: "audit_pg_1",
+      action: "feature.update",
+      outcome: "success",
+      actor: { id: "user_1", type: "user", name: "开发人员" },
+      target: { type: "features", id: "system.audit" },
+      occurredAt: "2026-07-10T00:00:00.000Z",
+    };
+
+    await writer.write(event);
+    await writer.write(event);
+
+    const result = await pool.query<{ count: string }>(
+      "select count(*)::text as count from audit_logs where id = $1",
+      [event.id],
+    );
+    expect(result.rows[0]?.count).toBe("1");
+  });
+});

package/template/apps/server/src/persistence.ts

@@ -0,0 +1,118 @@
+import type { PlatformConfig } from "@windy/config";
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import type { AuditWriteStatus } from "./audit/contracts.js";
+// @windy-module system.audit begin
+import {
+  DrizzleAuditLogReader,
+  DrizzleAuditLogWriter,
+} from "./audit/drizzle-log-store.js";
+import { FileAuditRecoveryQueue } from "./audit/recovery-queue.js";
+import { ReliableAuditWriter } from "./audit/reliable-writer.js";
+// @windy-module system.audit end
+import { RepositoryActorResolver } from "./auth/actor-resolver.js";
+import { readDevelopmentAuthBypass } from "./auth/development-bypass.js";
+import { DrizzleAuthRepository } from "./auth/drizzle-repository.js";
+// @windy-module system.license begin
+import { DrizzleLicenseEntitlementResolver } from "./license/license-resolver.js";
+// @windy-module system.license end
+// @windy-module system.configuration begin
+import { DrizzleModuleConfigVersionRepository } from "./configuration/drizzle-repository.js";
+// @windy-module system.configuration end
+
+export interface ServerPersistence {
+  actorResolver: RepositoryActorResolver;
+  authRepository: DrizzleAuthRepository;
+  // @windy-module system.audit begin
+  auditReader: DrizzleAuditLogReader;
+  auditWriter: ReliableAuditWriter;
+  // @windy-module system.audit end
+  // @windy-module system.license begin
+  licenseResolver: DrizzleLicenseEntitlementResolver;
+  // @windy-module system.license end
+  // @windy-module system.configuration begin
+  configVersionRepository: DrizzleModuleConfigVersionRepository;
+  // @windy-module system.configuration end
+  db: NodePgDatabase;
+  pool: Pool;
+}
+
+export function createServerPersistence(
+  env: Record<string, string | undefined>,
+  onAuditAlert?: (status: AuditWriteStatus) => void,
+  platformConfig?: PlatformConfig,
+): ServerPersistence | undefined {
+  const databaseUrl = platformConfig?.database.url || env.DATABASE_URL;
+  if (!databaseUrl) {
+    return undefined;
+  }
+
+  const pool = new Pool({ connectionString: databaseUrl });
+  const db = drizzle(pool);
+  const authRepository = new DrizzleAuthRepository(db);
+  // @windy-module system.audit begin
+  const auditWriter = new ReliableAuditWriter(
+    new DrizzleAuditLogWriter(db),
+    new FileAuditRecoveryQueue(
+      env.WINDY_AUDIT_QUEUE_FILE || "./data/audit/recovery-queue.json",
+    ),
+    {
+      maxAttempts: readPositiveInteger(env.WINDY_AUDIT_MAX_ATTEMPTS, 3),
+      baseDelayMs: readPositiveInteger(env.WINDY_AUDIT_RETRY_BASE_MS, 50),
+      maxDelayMs: readPositiveInteger(env.WINDY_AUDIT_RETRY_MAX_MS, 500),
+      maxQueueSize: readPositiveInteger(env.WINDY_AUDIT_QUEUE_SIZE, 1_000),
+      sensitiveFields:
+        platformConfig?.audit.redactFields ||
+        readSensitiveFields(env.AUDIT_REDACT_FIELDS),
+      onAlert: onAuditAlert,
+    },
+  );
+  // @windy-module system.audit end
+  const developmentAuth = readDevelopmentAuthBypass(env);
+  return {
+    actorResolver: new RepositoryActorResolver(authRepository, {
+      developmentTokenUsers: developmentAuth.token
+        ? { [developmentAuth.token]: "user_dev_admin" }
+        : {},
+      allowDevelopmentUserTokens: developmentAuth.allowDirectUserTokens,
+      userTokenPrefix: env.WINDY_DB_USER_TOKEN_PREFIX || "user:",
+      sessionCookieName:
+        platformConfig?.security.sessionCookieName ||
+        env.SESSION_COOKIE_NAME ||
+        "windy.sid",
+    }),
+    authRepository,
+    // @windy-module system.audit begin
+    auditReader: new DrizzleAuditLogReader(db),
+    auditWriter,
+    // @windy-module system.audit end
+    // @windy-module system.configuration begin
+    configVersionRepository: new DrizzleModuleConfigVersionRepository(db),
+    // @windy-module system.configuration end
+    // @windy-module system.license begin
+    licenseResolver: new DrizzleLicenseEntitlementResolver(db, {
+      machineCode:
+        env.WINDY_SERVER_MACHINE_CODE ||
+        platformConfig?.license.machineCode ||
+        env.LICENSE_MACHINE_CODE,
+    }),
+    // @windy-module system.license end
+    db,
+    pool,
+  };
+}
+
+function readPositiveInteger(
+  value: string | undefined,
+  fallback: number,
+): number {
+  const parsed = value ? Number.parseInt(value, 10) : Number.NaN;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function readSensitiveFields(value: string | undefined): string[] | undefined {
+  return value
+    ?.split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+}

package/template/apps/server/src/profile/routes.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import type { RequestActor } from "../guards.js";
+import { InMemoryAuthRepository } from "../auth/repository.js";
+import { createServerRuntime } from "../runtime.js";
+import type { RouteApp } from "../system/route-types.js";
+import { registerProfileRoutes } from "./routes.js";
+
+class FakeRouteApp implements RouteApp {
+  readonly handlers = new Map<string, (context: unknown) => unknown>();
+
+  get(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`GET ${path}`, handler);
+  }
+
+  post(): void {}
+
+  put(path: string, handler: (context: unknown) => unknown): void {
+    this.handlers.set(`PUT ${path}`, handler);
+  }
+
+  delete(): void {}
+
+  invoke(method: "GET" | "PUT", path: string, context: unknown): unknown {
+    const handler = this.handlers.get(`${method} ${path}`);
+    if (!handler) throw new Error(`未注册路由 ${method} ${path}`);
+    return handler(context);
+  }
+}
+
+describe("个人资料路由", () => {
+  test("只返回当前用户可编辑的个人资料字段", async () => {
+    const fixture = await createFixture(profileActor(true));
+
+    const profile = await fixture.app.invoke("GET", "/system/profile", {
+      guardContext: fixture.guardContext,
+      params: {},
+      query: {},
+    });
+
+    expect(profile).toEqual({
+      id: "user_profile",
+      username: "profile.admin",
+      displayName: "平台管理员",
+      email: "admin@example.com",
+      phone: "13800138000",
+    });
+    expect(profile).not.toHaveProperty("passwordHash");
+    expect(profile).not.toHaveProperty("permissionKeys");
+  });
+
+  test("用户可更新自己的姓名、邮箱和手机并写入审计", async () => {
+    const fixture = await createFixture(profileActor(true));
+
+    const updated = await fixture.app.invoke("PUT", "/system/profile", {
+      guardContext: fixture.guardContext,
+      body: {
+        displayName: "南风管理员",
+        email: "new@example.com",
+        phone: "13900139000",
+      },
+      params: {},
+      query: {},
+    });
+
+    expect(updated).toEqual({
+      id: "user_profile",
+      username: "profile.admin",
+      displayName: "南风管理员",
+      email: "new@example.com",
+      phone: "13900139000",
+    });
+    await expect(
+      fixture.repository.findUserByReference("user_profile"),
+    ).resolves.toMatchObject({ displayName: "南风管理员" });
+    expect(fixture.runtime.auditSink.list()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          action: "user.profile.update",
+          target: { type: "user-profile", id: "user_profile" },
+        }),
+      ]),
+    );
+  });
+
+  test("只读账号与关闭的 Feature 都不能修改个人资料", async () => {
+    const readonly = await createFixture(profileActor(false));
+    const missingPermission = (await readonly.app.invoke(
+      "PUT",
+      "/system/profile",
+      updateContext(readonly.guardContext),
+    )) as Response;
+    expect(missingPermission.status).toBe(403);
+    await expect(missingPermission.json()).resolves.toMatchObject({
+      reason: "missing-permission",
+    });
+
+    const disabled = await createFixture(profileActor(true), false);
+    const featureDisabled = (await disabled.app.invoke(
+      "PUT",
+      "/system/profile",
+      updateContext(disabled.guardContext),
+    )) as Response;
+    expect(featureDisabled.status).toBe(403);
+    await expect(featureDisabled.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+  });
+
+  test("非法邮箱和空姓名返回 400 且不修改资料", async () => {
+    const fixture = await createFixture(profileActor(true));
+    const response = (await fixture.app.invoke("PUT", "/system/profile", {
+      guardContext: fixture.guardContext,
+      body: { displayName: "  ", email: "not-an-email" },
+      params: {},
+      query: {},
+    })) as Response;
+
+    expect(response.status).toBe(400);
+    await expect(
+      fixture.repository.findUserByReference("user_profile"),
+    ).resolves.toMatchObject({ displayName: "平台管理员" });
+  });
+});
+
+async function createFixture(actor: RequestActor, featureEnabled = true) {
+  const repository = new InMemoryAuthRepository([
+    {
+      id: "user_profile",
+      username: "profile.admin",
+      displayName: "平台管理员",
+      email: "admin@example.com",
+      phone: "13800138000",
+      passwordHash: "secret",
+      credentialState: "active",
+      status: "active",
+      roleCodes: ["admin"],
+      permissionKeys: [...actor.permissionKeys],
+    },
+  ]);
+  const runtime = createServerRuntime(
+    {},
+    {
+      actorResolver: { resolve: () => actor },
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: featureEnabled,
+          visible: "visible",
+        }),
+      },
+    },
+  );
+  const app = new FakeRouteApp();
+  registerProfileRoutes(
+    app,
+    repository,
+    runtime,
+    createFoundationSnapshot().features,
+  );
+  const guardContext = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/profile"),
+  );
+  return { app, repository, runtime, guardContext };
+}
+
+function profileActor(canManage: boolean): RequestActor {
+  return {
+    id: "user_profile",
+    type: "user",
+    name: "平台管理员",
+    username: "profile.admin",
+    displayName: "平台管理员",
+    email: "admin@example.com",
+    phone: "13800138000",
+    roleCodes: ["admin"],
+    permissionKeys: ["system.profile.read"].concat(
+      canManage ? "system.profile.manage" : [],
+    ),
+  };
+}
+
+function updateContext(guardContext: unknown) {
+  return {
+    guardContext,
+    body: { displayName: "新名字" },
+    params: {},
+    query: {},
+  };
+}