create-windy 0.8.3 → 0.10.0

package/template/apps/server/src/system/diagnostic-routes.ts

@@ -0,0 +1,101 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  expiredDiagnosticId,
+  validDiagnosticId,
+  type DiagnosticIndex,
+} from "../observability/diagnostic-index.js";
+import { parsePagination } from "../pagination.js";
+import { findFeature } from "../route-guards.js";
+import { resourceEvent, routeContext } from "./route-helpers.js";
+import { withPermission } from "./resource-route-support.js";
+import type { RouteApp } from "./route-types.js";
+
+export function registerDiagnosticRoutes(
+  app: Pick<RouteApp, "get">,
+  runtime: ReturnType<typeof createServerRuntime>,
+  features: FeatureFlagDefinition[],
+  index: DiagnosticIndex,
+) {
+  const feature = findFeature(features, "system.diagnostics");
+  if (!feature) throw new Error("错误诊断缺少 system.diagnostics Feature");
+  app.get("/system/diagnostics", (raw) => {
+    const { query, guardContext } = routeContext(raw);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      "diagnostics",
+      "read",
+      feature,
+      async () => {
+        const pagination = parsePagination(query);
+        if (pagination instanceof Response) return pagination;
+        try {
+          await runtime.auditSink.recordCriticalEvent(
+            resourceEvent(
+              guardContext,
+              "diagnostic.read",
+              "diagnostic-events",
+              undefined,
+              {
+                page: pagination.page,
+                pageSize: pagination.pageSize,
+              },
+            ),
+          );
+          return Response.json(await index.list(pagination), {
+            headers: { "cache-control": "no-store" },
+          });
+        } catch {
+          return failure("DIAGNOSTIC_INDEX_UNAVAILABLE", 503);
+        }
+      },
+    );
+  });
+  app.get("/system/diagnostics/:diagnosticId", (raw) => {
+    const { params, guardContext } = routeContext(raw);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      "diagnostics",
+      "read",
+      feature,
+      async () => {
+        const id = params.diagnosticId ?? "";
+        if (/^web-[0-9a-f-]{36}$/.test(id))
+          return failure("CLIENT_ONLY_DIAGNOSTIC", 422);
+        if (!validDiagnosticId(id))
+          return failure("INVALID_DIAGNOSTIC_ID", 400);
+        try {
+          await runtime.auditSink.recordCriticalEvent(
+            resourceEvent(
+              guardContext,
+              "diagnostic.read",
+              "diagnostic-events",
+              id,
+            ),
+          );
+          if (expiredDiagnosticId(id))
+            return failure("DIAGNOSTIC_EXPIRED", 410);
+          const record = await index.find(id);
+          return record
+            ? Response.json(record, {
+                headers: { "cache-control": "no-store" },
+              })
+            : failure("DIAGNOSTIC_NOT_FOUND", 404);
+        } catch {
+          return failure("DIAGNOSTIC_INDEX_UNAVAILABLE", 503);
+        }
+      },
+    );
+  });
+}
+
+function failure(error: string, status: number) {
+  return Response.json(
+    { error },
+    { status, headers: { "cache-control": "no-store" } },
+  );
+}

package/template/apps/server/src/system/environment-policy-reader.test.ts

@@ -0,0 +1,74 @@
+import { parseEnvironmentPolicy } from "@southwind-ai/shared";
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createEnvironmentPolicyReader } from "./environment-policy-reader.js";
+
+test("bounded policy reader rejects invalid, oversized and symlink files without exposing contents", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "windy-policy-"));
+  try {
+    const file = join(directory, "policy.yaml");
+    await writeFile(file, "private-secret-input");
+    const result = await createEnvironmentPolicyReader(file)();
+    expect(result.status).toBe("invalid");
+    expect(JSON.stringify(result)).not.toContain("private-secret-input");
+    await writeFile(file, " ".repeat(128 * 1024 + 1));
+    expect((await createEnvironmentPolicyReader(file)()).status).toBe(
+      "invalid",
+    );
+    await writeFile(
+      file,
+      "schemaVersion: 1\nbuild: { modules: [] }\nfeatures: []\n",
+    );
+    expect((await createEnvironmentPolicyReader(file)()).status).toBe(
+      "available",
+    );
+    const link = join(directory, "link");
+    await symlink(file, link);
+    expect((await createEnvironmentPolicyReader(link)()).status).toBe(
+      "invalid",
+    );
+    expect((await createEnvironmentPolicyReader(directory)()).status).toBe(
+      "invalid",
+    );
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test.skipIf(process.platform === "win32")(
+  "FIFO policy paths fail without waiting for a writer",
+  async () => {
+    const directory = await mkdtemp(join(tmpdir(), "windy-policy-fifo-"));
+    try {
+      const file = join(directory, "fifo");
+      const command = Bun.spawn(["mkfifo", file]);
+      expect(await command.exited).toBe(0);
+      expect((await createEnvironmentPolicyReader(file)()).status).toBe(
+        "invalid",
+      );
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  },
+  2000,
+);
+
+test("运行时开关保留显式关闭，拒绝未知能力和非布尔值", () => {
+  const base = { schemaVersion: 1, build: { modules: [] }, features: [] };
+  expect(parseEnvironmentPolicy(base).runtime).toBeUndefined();
+  const runtime = {
+    agent: false,
+    document: true,
+    speech: false,
+    embedding: false,
+  };
+  expect(parseEnvironmentPolicy({ ...base, runtime }).runtime).toEqual(runtime);
+  expect(() =>
+    parseEnvironmentPolicy({ ...base, runtime: { agent: "false" } }),
+  ).toThrow();
+  expect(() =>
+    parseEnvironmentPolicy({ ...base, runtime: { typo: true } }),
+  ).toThrow();
+});

package/template/apps/server/src/system/environment-policy-reader.ts

@@ -0,0 +1,62 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import {
+  parseEnvironmentPolicy,
+  type EnvironmentPolicy,
+} from "@southwind-ai/shared";
+
+/** Never return YAML contents or secrets in diagnostics. Reads are bounded even if a file grows. */
+export function createEnvironmentPolicyReader(
+  path = process.env.WINDY_ENVIRONMENT_PROFILE_FILE,
+) {
+  let cached: { at: number; result: EnvironmentPolicyRead } | undefined;
+  return async (): Promise<EnvironmentPolicyRead> => {
+    if (!path)
+      return {
+        status: "not-configured",
+        message: "未配置环境预设；不自动推断功能依赖。",
+      };
+    if (cached && Date.now() - cached.at < 5000) return cached.result;
+    let result: EnvironmentPolicyRead;
+    try {
+      const handle = await open(
+        path,
+        constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+      );
+      try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.size > 128 * 1024)
+          throw new Error("invalid file");
+        const buffer = Buffer.alloc(128 * 1024 + 1);
+        let bytesRead = 0;
+        while (bytesRead < buffer.length) {
+          const chunk = await handle.read(
+            buffer,
+            bytesRead,
+            buffer.length - bytesRead,
+            bytesRead,
+          );
+          if (chunk.bytesRead === 0) break;
+          bytesRead += chunk.bytesRead;
+        }
+        if (bytesRead > 128 * 1024) throw new Error("oversized");
+        const policy = parseEnvironmentPolicy(
+          Bun.YAML.parse(buffer.subarray(0, bytesRead).toString("utf8")),
+        );
+        result = { status: "available", policy };
+      } finally {
+        await handle.close();
+      }
+    } catch {
+      result = {
+        status: "invalid",
+        message: "环境预设不可读、超出大小限制或格式无效；未改变任何功能。",
+      };
+    }
+    cached = { at: Date.now(), result };
+    return result;
+  };
+}
+export type EnvironmentPolicyRead =
+  | { status: "available"; policy: EnvironmentPolicy }
+  | { status: "not-configured" | "invalid"; message: string };

package/template/apps/server/src/system/feature-environment-assessment.test.ts

@@ -0,0 +1,148 @@
+import { expect, test } from "bun:test";
+import { featureKey, type FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { EnvironmentSnapshot } from "../../../../packages/shared/src/environment-assessment.js";
+import { parseEnvironmentPolicy } from "../../../../packages/shared/src/environment-policy.js";
+import {
+  assessFeatureEnvironment,
+  type FeatureAssessmentInput,
+} from "./feature-environment-assessment.js";
+
+const feature: FeatureFlagDefinition = {
+  key: featureKey("example.ocr"),
+  label: "CPU OCR",
+  module: "example",
+  enabled: true,
+  visible: "visible",
+  stage: "stable",
+};
+function input(): FeatureAssessmentInput {
+  return {
+    definitions: [feature],
+    resolveEnabled: async () => true,
+    environment: {
+      generatedAt: new Date().toISOString(),
+      process: {
+        scope: "process",
+        platform: "linux",
+        architecture: "arm64",
+        nodeVersion: "test",
+        containerized: true,
+        logicalCpuCount: 2,
+        memoryTotalBytes: 1024,
+      },
+      host: { status: "not-configured", message: "unknown" },
+    },
+  };
+}
+function policy(
+  execution: "cpu" | "local-gpu" | "remote" = "cpu",
+  extra: Record<string, unknown> = {},
+) {
+  return {
+    status: "available" as const,
+    policy: parseEnvironmentPolicy({
+      schemaVersion: 1,
+      build: { modules: ["system"] },
+      features: [{ key: "example.ocr", title: "OCR", execution, ...extra }],
+    }),
+  };
+}
+test("missing host GPU evidence is unknown; CPU OCR is not disabled by missing GPU", async () => {
+  expect(
+    (await assessFeatureEnvironment(policy("local-gpu"), input())).features[0]
+      ?.status,
+  ).toBe("unknown");
+  expect(
+    (await assessFeatureEnvironment(policy("cpu"), input())).features[0]
+      ?.status,
+  ).toBe("available");
+});
+test("software support and missing configuration are distinct from hardware", async () => {
+  expect(
+    (
+      await assessFeatureEnvironment(
+        policy("cpu", { supportedArchitectures: ["x64"] }),
+        input(),
+      )
+    ).features[0]?.status,
+  ).toBe("software");
+  const result = await assessFeatureEnvironment(
+    policy("remote", { requiredEnvironmentKeys: ["MODEL_TOKEN"] }),
+    input(),
+  );
+  expect(result.features[0]?.status).toBe("configuration");
+  const configured = {
+    ...input(),
+    environmentValues: { MODEL_TOKEN: "do-not-leak" },
+  };
+  expect(
+    JSON.stringify(
+      await assessFeatureEnvironment(
+        policy("remote", { requiredEnvironmentKeys: ["MODEL_TOKEN"] }),
+        configured,
+      ),
+    ),
+  ).not.toContain("do-not-leak");
+});
+test("remote execution does not require local GPU or local model memory", async () => {
+  const result = await assessFeatureEnvironment(
+    policy("remote", { minMemoryGiB: 64 }),
+    input(),
+  );
+  expect(result.features[0]?.status).toBe("available");
+});
+test("valid insufficient host memory is hardware; stale evidence cannot reject hardware", async () => {
+  const value = input();
+  value.environment.host = {
+    status: "available",
+    message: "fixture",
+    report: {
+      collectedAt: new Date().toISOString(),
+      facts: { memoryTotalBytes: 1024 ** 3 },
+    } as NonNullable<EnvironmentSnapshot["host"]["report"]>,
+  };
+  expect(
+    (await assessFeatureEnvironment(policy("cpu", { minMemoryGiB: 8 }), value))
+      .features[0]?.status,
+  ).toBe("hardware");
+  value.environment.host.status = "stale";
+  expect(
+    (await assessFeatureEnvironment(policy("cpu", { minMemoryGiB: 8 }), value))
+      .features[0]?.status,
+  ).toBe("unknown");
+});
+test("package absence, explicit disable and resolver failure retain distinct states", async () => {
+  expect(
+    (await assessFeatureEnvironment(policy(), { ...input(), definitions: [] }))
+      .features[0]?.status,
+  ).toBe("not-packaged");
+  expect(
+    (
+      await assessFeatureEnvironment(policy(), {
+        ...input(),
+        resolveEnabled: async () => false,
+      })
+    ).features[0]?.status,
+  ).toBe("disabled");
+  expect(
+    (
+      await assessFeatureEnvironment(policy(), {
+        ...input(),
+        resolveEnabled: async () => {
+          throw new Error("private");
+        },
+      })
+    ).features[0]?.status,
+  ).toBe("unknown");
+});
+test("unknown policy fields, duplicate feature keys and invalid booleans are rejected", () => {
+  expect(() => policy("cpu", { recommendedEnabled: "false" })).toThrow();
+  expect(() => policy("cpu", { secretlyEnable: true })).toThrow();
+  const parsed = policy().policy;
+  expect(() =>
+    parseEnvironmentPolicy({
+      ...parsed,
+      features: [...parsed.features, ...parsed.features],
+    }),
+  ).toThrow();
+});

package/template/apps/server/src/system/feature-environment-assessment.ts

@@ -0,0 +1,179 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { EnvironmentSnapshot } from "../../../../packages/shared/src/environment-assessment.js";
+import type {
+  EnvironmentAssessmentSnapshot,
+  FeatureEnvironmentAssessment,
+  FeatureEnvironmentPolicy,
+} from "../../../../packages/shared/src/environment-policy.js";
+import type { EnvironmentPolicyRead } from "./environment-policy-reader.js";
+
+export interface FeatureAssessmentInput {
+  environment: EnvironmentSnapshot;
+  definitions: readonly FeatureFlagDefinition[];
+  resolveEnabled: (definition: FeatureFlagDefinition) => Promise<boolean>;
+  environmentValues?: Record<string, string | undefined>;
+}
+
+/** Advisory only: never changes features, licenses, running tasks, or build contents. */
+export async function assessFeatureEnvironment(
+  source: EnvironmentPolicyRead,
+  input: FeatureAssessmentInput,
+): Promise<EnvironmentAssessmentSnapshot> {
+  if (source.status !== "available") return { ...source, features: [] };
+  const definitions = new Map(
+    input.definitions.map((item) => [String(item.key), item]),
+  );
+  const features = await Promise.all(
+    source.policy.features.map(async (policy) => {
+      const definition = definitions.get(policy.key);
+      if (!definition)
+        return result(
+          policy,
+          "not-packaged",
+          "当前装配未注册此功能；请核对功能 Key 与交付模块。",
+          [],
+        );
+      let enabled: boolean;
+      try {
+        enabled = await input.resolveEnabled(definition);
+      } catch {
+        return result(
+          policy,
+          "unknown",
+          "功能开关状态读取失败；未修改配置。",
+          [],
+        );
+      }
+      return assessRequirements(policy, input, enabled);
+    }),
+  );
+  return {
+    status: "available",
+    message:
+      "评估只生成建议；请管理员核对证据后在功能管理中确认关闭。条件满足不代表模型或业务已验收。",
+    features,
+  };
+}
+function result(
+  policy: FeatureEnvironmentPolicy,
+  status: FeatureEnvironmentAssessment["status"],
+  message: string,
+  evidence: string[],
+): FeatureEnvironmentAssessment {
+  return {
+    key: policy.key,
+    title: policy.title,
+    status,
+    message,
+    evidence,
+    ...(policy.recommendedEnabled === undefined
+      ? {}
+      : { recommendedEnabled: policy.recommendedEnabled }),
+  };
+}
+function assessRequirements(
+  policy: FeatureEnvironmentPolicy,
+  input: FeatureAssessmentInput,
+  enabled: boolean,
+) {
+  const process = input.environment.process;
+  const evidence = [
+    `当前功能开关：${enabled ? "开启" : "关闭"}`,
+    `应用进程：${process.platform}/${process.architecture}；此信息不代表宿主机硬件`,
+    `声明执行方式：${policy.execution}`,
+  ];
+  if (
+    policy.supportedPlatforms?.length &&
+    !policy.supportedPlatforms.includes(process.platform)
+  )
+    return result(
+      policy,
+      "software",
+      "当前应用运行平台不在声明支持范围；更换硬件不一定能解决。",
+      evidence,
+    );
+  if (
+    policy.supportedArchitectures?.length &&
+    !policy.supportedArchitectures.includes(process.architecture)
+  )
+    return result(
+      policy,
+      "software",
+      "当前应用架构不在声明的软件支持范围；需匹配的软件构建。",
+      evidence,
+    );
+  const missing = (policy.requiredEnvironmentKeys ?? []).filter(
+    (key) => !(input.environmentValues ?? {})[key]?.trim(),
+  );
+  if (missing.length)
+    return result(policy, "configuration", "所需配置未就绪；不能归因于硬件。", [
+      ...evidence,
+      `缺少配置项：${missing.join("、")}`,
+    ]);
+  const needsHost =
+    policy.execution !== "remote" &&
+    (policy.execution === "local-gpu" || policy.minMemoryGiB !== undefined);
+  if (needsHost) {
+    const host = input.environment.host;
+    if (host.status !== "available" || !host.report)
+      return result(
+        policy,
+        "unknown",
+        "缺少有效宿主机证据；容器中未检测到设备不等于宿主机没有设备。",
+        evidence,
+      );
+    evidence.push(`宿主机采集时间：${host.report.collectedAt}`);
+    const facts = host.report.facts;
+    if (policy.minMemoryGiB !== undefined) {
+      if (facts.memoryTotalBytes === null)
+        return result(
+          policy,
+          "unknown",
+          "宿主机内存数据未知，无法判断最低内存条件。",
+          evidence,
+        );
+      evidence.push(
+        `宿主机总内存：${(facts.memoryTotalBytes / 1024 ** 3).toFixed(1)} GiB；要求至少 ${policy.minMemoryGiB} GiB`,
+      );
+      if (facts.memoryTotalBytes < policy.minMemoryGiB * 1024 ** 3)
+        return result(
+          policy,
+          "hardware",
+          "宿主机总内存低于声明的最低要求。",
+          evidence,
+        );
+    }
+    if (policy.execution === "local-gpu") {
+      if (facts.gpuCount === undefined)
+        return result(
+          policy,
+          "unknown",
+          "未取得有效 NVIDIA GPU 查询；需核对设备、驱动、权限与采集工具。",
+          evidence,
+        );
+      evidence.push(`NVIDIA GPU 数量：${facts.gpuCount}`);
+      if (facts.gpuCount === 0)
+        return result(
+          policy,
+          "hardware",
+          "有效宿主机查询未返回所需 GPU；本地 GPU 执行条件不满足。",
+          evidence,
+        );
+    }
+  }
+  if (!enabled)
+    return result(
+      policy,
+      "disabled",
+      "功能当前已关闭；环境评估不会自动开启。",
+      evidence,
+    );
+  return result(
+    policy,
+    "available",
+    policy.execution === "none"
+      ? "声明条件已满足；仍以实际业务验收为准。"
+      : "声明条件已满足；模型 readiness、驱动兼容、容器配额及性能尚需单独验收。",
+    evidence,
+  );
+}