create-windy 0.5.2 → 0.6.1

package/template/packages/server-sdk/src/storage-v052-source-compatibility.test.ts

@@ -0,0 +1,61 @@
+import { expect, test } from "bun:test";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+import type { OpenedFile, UploadSession } from "@southwind-ai/storage";
+import type { ModuleDurableHandlerContext } from "./durable-handler.js";
+import type { ModuleRequestContext } from "./request-context.js";
+import type {
+  ModuleOpenedResourceFile,
+  ModuleResourceFileRequest,
+  ModuleUploadSessionInput,
+} from "./storage-port.js";
+
+interface Fixed052StorageMock {
+  createUploadSession(input: ModuleUploadSessionInput): Promise<UploadSession>;
+  openFile(fileId: string): Promise<OpenedFile>;
+  openPublicFile(fileId: string, purpose: string): Promise<OpenedFile>;
+  openResourceFile(
+    input: ModuleResourceFileRequest,
+  ): Promise<ModuleOpenedResourceFile>;
+}
+
+interface Fixed052RequestContext {
+  readonly requestId: string;
+  readonly actor: ModuleRequestContext["actor"];
+  readonly params: ModuleRequestContext["params"];
+  readonly query: ModuleRequestContext["query"];
+  readonly body?: unknown;
+  readonly audit: ModuleRequestContext["audit"];
+  readonly aiArtifacts: ModuleRequestContext["aiArtifacts"];
+  readonly aiOperations: ModuleRequestContext["aiOperations"];
+  readonly jobs: ModuleRequestContext["jobs"];
+  readonly storage: Fixed052StorageMock;
+  readonly userDirectory: ModuleRequestContext["userDirectory"];
+}
+
+interface Fixed052DurableContext extends DurableHandlerContext {
+  readonly actor: ModuleDurableHandlerContext["actor"];
+  readonly requestId: string;
+  readonly storage: {
+    openResourceFile(
+      input: ModuleResourceFileRequest,
+    ): Promise<ModuleOpenedResourceFile>;
+  };
+  readonly ai: ModuleDurableHandlerContext["ai"];
+}
+
+function acceptRequestContext(
+  context: Fixed052RequestContext,
+): ModuleRequestContext {
+  return context;
+}
+
+function acceptDurableContext(
+  context: Fixed052DurableContext,
+): ModuleDurableHandlerContext {
+  return context;
+}
+
+test("0.5.2 Request/Durable storage consumer source remains assignable", () => {
+  expect(typeof acceptRequestContext).toBe("function");
+  expect(typeof acceptDurableContext).toBe("function");
+});

package/template/packages/shared/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/audit.js";
+export * from "./src/ai-operation-readiness.js";
 // @windy-module system.agent begin
 export * from "./src/ai-runtime-report.js";
 // @windy-module system.agent end
@@ -22,4 +23,8 @@ export * from "./src/rbac.js";
 export * from "./src/ruoyi.js";
 export * from "./src/scheduler.js";
 export * from "./src/search-provider.js";
+// @windy-module system.agent begin
+export * from "./src/screenshot-context-digest.js";
+// @windy-module system.agent end
+export * from "./src/stable-key.js";
 export * from "./src/workflow.js";

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -11,6 +11,9 @@
     "src/**/*.ts",
     "!src/**/*.test.ts"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
   "exports": {
     ".": "./index.ts"
   },

package/template/packages/shared/src/ai-operation-readiness.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1,
+  validAiOperationReadinessRequirementV1,
+} from "./ai-operation-readiness.js";
+
+const requirement = () => ({
+  schemaVersion: 1,
+  operationKey: "evidence.document.ocr",
+  runtimeKind: "document",
+  expectedDeployment: {
+    key: "document.intranet",
+    identity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+    releaseDigest: `sha256:${"a".repeat(64)}`,
+    offersDigest: `sha256:${"b".repeat(64)}`,
+  },
+  variant: "ocr",
+  requiredCapabilities: ["document.ocr"],
+  inputModalities: ["document"],
+  outputModalities: ["document", "text"],
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 4_096,
+    maxOutputBytes: 4_096,
+    maxUnits: 20,
+  },
+  resources: { minConcurrentRuns: 1, minQueueDepth: 0 },
+});
+
+describe("AI Operation readiness shared contract", () => {
+  test("接受完整 V1 requirement", () => {
+    expect(validAiOperationReadinessRequirementV1(requirement())).toBe(true);
+  });
+
+  test.each([
+    ["非法 deployment identity", () => ({ identity: "document.intranet" })],
+    ["空白 deployment key", () => ({ key: " " })],
+    ["空白 variant", () => ({ variant: " " })],
+  ])("拒绝%s", (_label, mutate) => {
+    const value = requirement();
+    const changes = mutate();
+    if ("variant" in changes) Object.assign(value, changes);
+    else Object.assign(value.expectedDeployment, changes);
+    expect(validAiOperationReadinessRequirementV1(value)).toBe(false);
+  });
+
+  test("拒绝重复模态和 capability cardinality 越界", () => {
+    const duplicateModality = requirement();
+    duplicateModality.inputModalities = ["document", "document"];
+    expect(validAiOperationReadinessRequirementV1(duplicateModality)).toBe(
+      false,
+    );
+
+    const tooManyCapabilities = requirement();
+    tooManyCapabilities.requiredCapabilities = Array.from(
+      { length: AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1 + 1 },
+      (_, index) => `document.capability-${index}`,
+    );
+    expect(validAiOperationReadinessRequirementV1(tooManyCapabilities)).toBe(
+      false,
+    );
+  });
+
+  test("拒绝不安全或越界 resource 数值", () => {
+    const unsafeConcurrent = requirement();
+    unsafeConcurrent.resources.minConcurrentRuns = Number.MAX_SAFE_INTEGER + 1;
+    expect(validAiOperationReadinessRequirementV1(unsafeConcurrent)).toBe(
+      false,
+    );
+
+    const negativeQueue = requirement();
+    negativeQueue.resources.minQueueDepth = -1;
+    expect(validAiOperationReadinessRequirementV1(negativeQueue)).toBe(false);
+  });
+});

package/template/packages/shared/src/ai-operation-readiness.ts

@@ -0,0 +1,170 @@
+export const AI_RUNTIME_READINESS_SCHEMA_VERSION = 1 as const;
+export const AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1 = 16 as const;
+
+export const AI_RUNTIME_KINDS_V1 = [
+  "agent",
+  "document",
+  "speech",
+  "embedding",
+] as const;
+
+export type AiRuntimeKindV1 = (typeof AI_RUNTIME_KINDS_V1)[number];
+
+export const AI_RUNTIME_MODALITIES_V1 = [
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document",
+  "embedding",
+] as const;
+
+export type AiRuntimeModalityV1 = (typeof AI_RUNTIME_MODALITIES_V1)[number];
+export type AiRuntimeReleaseDigestV1 = `sha256:${string}`;
+export type AiRuntimeOffersDigestV1 = `sha256:${string}`;
+
+export interface AiRuntimeDeploymentV1 {
+  readonly key: string;
+  readonly identity: string;
+  readonly releaseDigest: AiRuntimeReleaseDigestV1;
+  readonly offersDigest: AiRuntimeOffersDigestV1;
+}
+
+export interface AiOperationRequiredLimitsV1 {
+  readonly maxDurationSeconds: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+  readonly maxUnits?: number;
+  readonly maxMediaDurationSeconds?: number;
+  readonly maxArtifacts?: number;
+  readonly maxPixelsPerArtifact?: number;
+}
+
+export interface AiOperationRequiredResourcesV1 {
+  readonly minConcurrentRuns: number;
+  readonly minQueueDepth: number;
+}
+
+export interface AiOperationReadinessRequirementV1 {
+  readonly schemaVersion: typeof AI_RUNTIME_READINESS_SCHEMA_VERSION;
+  readonly operationKey: string;
+  readonly runtimeKind: AiRuntimeKindV1;
+  readonly expectedDeployment: AiRuntimeDeploymentV1;
+  readonly variant?: string;
+  readonly requiredCapabilities: readonly string[];
+  readonly inputModalities: readonly AiRuntimeModalityV1[];
+  readonly outputModalities: readonly AiRuntimeModalityV1[];
+  readonly limits: AiOperationRequiredLimitsV1;
+  readonly resources: AiOperationRequiredResourcesV1;
+}
+
+const stableKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const deploymentIdentityPattern =
+  /^windy-deployment-v1_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+const runtimeKinds = new Set<string>(AI_RUNTIME_KINDS_V1);
+const runtimeModalities = new Set<string>(AI_RUNTIME_MODALITIES_V1);
+const requiredLimitKeys = [
+  "maxDurationSeconds",
+  "maxInputBytes",
+  "maxOutputBytes",
+] as const;
+const optionalLimitKeys = [
+  "maxUnits",
+  "maxMediaDurationSeconds",
+  "maxArtifacts",
+  "maxPixelsPerArtifact",
+] as const;
+
+/** Pure contract guard shared by Manifest composition and Host projection. */
+export function validAiOperationReadinessRequirementV1(
+  requirement: unknown,
+): requirement is AiOperationReadinessRequirementV1 {
+  if (!isRecord(requirement)) return false;
+  return (
+    requirement.schemaVersion === AI_RUNTIME_READINESS_SCHEMA_VERSION &&
+    validStableKey(requirement.operationKey) &&
+    typeof requirement.runtimeKind === "string" &&
+    runtimeKinds.has(requirement.runtimeKind) &&
+    validDeployment(requirement.expectedDeployment) &&
+    (requirement.variant === undefined ||
+      validStableKey(requirement.variant)) &&
+    validStableKeyList(
+      requirement.requiredCapabilities,
+      AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1,
+    ) &&
+    validModalities(requirement.inputModalities) &&
+    validModalities(requirement.outputModalities) &&
+    validLimits(requirement.limits) &&
+    validResources(requirement.resources)
+  );
+}
+
+function validDeployment(value: unknown): value is AiRuntimeDeploymentV1 {
+  return (
+    isRecord(value) &&
+    validStableKey(value.key) &&
+    typeof value.identity === "string" &&
+    deploymentIdentityPattern.test(value.identity) &&
+    typeof value.releaseDigest === "string" &&
+    digestPattern.test(value.releaseDigest) &&
+    typeof value.offersDigest === "string" &&
+    digestPattern.test(value.offersDigest)
+  );
+}
+
+function validStableKey(value: unknown): value is string {
+  return typeof value === "string" && stableKeyPattern.test(value);
+}
+
+function validStableKeyList(value: unknown, maximum: number): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= maximum &&
+    value.every(validStableKey) &&
+    new Set(value).size === value.length
+  );
+}
+
+function validModalities(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= AI_RUNTIME_MODALITIES_V1.length &&
+    value.every(
+      (item) => typeof item === "string" && runtimeModalities.has(item),
+    ) &&
+    new Set(value).size === value.length
+  );
+}
+
+function validLimits(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return (
+    requiredLimitKeys.every((key) => positiveSafeInteger(value[key])) &&
+    optionalLimitKeys.every(
+      (key) => value[key] === undefined || positiveSafeInteger(value[key]),
+    )
+  );
+}
+
+function validResources(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    positiveSafeInteger(value.minConcurrentRuns) &&
+    nonNegativeSafeInteger(value.minQueueDepth)
+  );
+}
+
+function positiveSafeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && Number(value) > 0;
+}
+
+function nonNegativeSafeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/packages/shared/src/license-catalog.ts

@@ -81,20 +81,25 @@ export function parseLicenseCatalog(
     if (unknownField) {
       throw new Error(`License 版本目录包含未知字段：${unknownField}`);
     }
+    const description = record.description;
+    const key = record.key;
+    const label = record.label;
+    const order = record.order;
     if (
-      typeof record.key !== "string" ||
-      typeof record.label !== "string" ||
-      (record.description !== undefined &&
-        typeof record.description !== "string") ||
-      typeof record.order !== "number"
+      typeof key !== "string" ||
+      typeof label !== "string" ||
+      (description !== undefined && typeof description !== "string") ||
+      typeof order !== "number"
     ) {
       throw new Error(`License 版本目录第 ${index + 1} 项字段类型无效`);
     }
+    const normalizedDescription =
+      typeof description === "string" ? description.trim() : "";
     return {
-      key: licenseVersionKey(record.key.trim()),
-      label: record.label.trim(),
-      description: record.description?.trim() ?? "",
-      order: record.order,
+      key: licenseVersionKey(key.trim()),
+      label: label.trim(),
+      description: normalizedDescription,
+      order,
     };
   });
   validateLicenseCatalog(catalog);

package/template/packages/shared/src/screenshot-context-digest.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  canonicalizeScreenshotContextV1,
+  computeScreenshotContextDigestV1,
+  isScreenshotContextDigestV1,
+} from "./screenshot-context-digest.js";
+
+describe("Screenshot context digest V1", () => {
+  test("Web 与 Host 对 key 顺序不同的结构化上下文得到同一摘要", async () => {
+    const first = {
+      version: 1,
+      pageKey: "case.detail",
+      overlayStack: [{ title: "导入物证", kind: "dialog" }],
+    };
+    const reordered = {
+      overlayStack: [{ kind: "dialog", title: "导入物证" }],
+      pageKey: "case.detail",
+      version: 1,
+    };
+
+    expect(canonicalizeScreenshotContextV1(first)).toBe(
+      '{"overlayStack":[{"kind":"dialog","title":"导入物证"}],"pageKey":"case.detail","version":1}',
+    );
+    expect(await computeScreenshotContextDigestV1(first)).toBe(
+      "sha256:3e274a367806437443ac78bb6955445c5af2ba924f89d113ba6f652c1d6a3905",
+    );
+    expect(await computeScreenshotContextDigestV1(reordered)).toBe(
+      await computeScreenshotContextDigestV1(first),
+    );
+    expect(
+      isScreenshotContextDigestV1(
+        await computeScreenshotContextDigestV1(first),
+      ),
+    ).toBe(true);
+  });
+
+  test("拒绝非有限数值与非 plain JSON", async () => {
+    expect(() => canonicalizeScreenshotContextV1(Number.NaN)).toThrow(
+      "数值无效",
+    );
+    expect(() => canonicalizeScreenshotContextV1(new Date() as never)).toThrow(
+      "plain JSON",
+    );
+    expect(isScreenshotContextDigestV1(`sha256:${"A".repeat(64)}`)).toBe(false);
+  });
+});

package/template/packages/shared/src/screenshot-context-digest.ts

@@ -0,0 +1,72 @@
+import type { JsonValue } from "./json.js";
+
+const MAX_DEPTH = 32;
+const MAX_NODES = 4_096;
+const MAX_CANONICAL_BYTES = 256 * 1_024;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+export type ScreenshotContextDigestV1 = `sha256:${string}`;
+
+/** Web/Host 共用的稳定 JSON：object key 排序，array 顺序与 JSON 数值语义保持不变。 */
+export function canonicalizeScreenshotContextV1(value: JsonValue): string {
+  let nodes = 0;
+  const visit = (item: JsonValue, depth: number): string => {
+    nodes += 1;
+    if (nodes > MAX_NODES || depth > MAX_DEPTH) {
+      throw new Error("Screenshot context 超过稳定摘要边界");
+    }
+    if (
+      item === null ||
+      typeof item === "boolean" ||
+      typeof item === "string"
+    ) {
+      return JSON.stringify(item);
+    }
+    if (typeof item === "number") {
+      if (!Number.isFinite(item))
+        throw new Error("Screenshot context 数值无效");
+      return JSON.stringify(item);
+    }
+    if (Array.isArray(item)) {
+      if (item.length > MAX_NODES) {
+        throw new Error("Screenshot context 数组超过稳定摘要边界");
+      }
+      return `[${item.map((entry) => visit(entry, depth + 1)).join(",")}]`;
+    }
+    const prototype = Object.getPrototypeOf(item);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error("Screenshot context 必须是 plain JSON");
+    }
+    const keys = Object.keys(item).sort();
+    return `{${keys
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${visit(item[key] as JsonValue, depth + 1)}`,
+      )
+      .join(",")}}`;
+  };
+  const canonical = visit(value, 0);
+  if (new TextEncoder().encode(canonical).byteLength > MAX_CANONICAL_BYTES) {
+    throw new Error("Screenshot context 超过稳定摘要字节边界");
+  }
+  return canonical;
+}
+
+export async function computeScreenshotContextDigestV1(
+  value: JsonValue,
+): Promise<ScreenshotContextDigestV1> {
+  const bytes = new TextEncoder().encode(
+    canonicalizeScreenshotContextV1(value),
+  );
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  const hex = [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  return `sha256:${hex}`;
+}
+
+export function isScreenshotContextDigestV1(
+  value: unknown,
+): value is ScreenshotContextDigestV1 {
+  return typeof value === "string" && DIGEST_PATTERN.test(value);
+}

package/template/packages/shared/src/stable-key.ts

@@ -0,0 +1,26 @@
+const STABLE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+
+export const STABLE_KEY_MAX_LENGTH = 128;
+
+export function isStableKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= STABLE_KEY_MAX_LENGTH &&
+    STABLE_KEY_PATTERN.test(value)
+  );
+}
+
+export function requireStableModuleKey(
+  kind: string,
+  value: unknown,
+  moduleName: string,
+): asserts value is string {
+  if (!isStableKey(value)) {
+    throw new Error(
+      `${kind}必须是最多 ${STABLE_KEY_MAX_LENGTH} 字符的小写稳定 Key`,
+    );
+  }
+  if (value !== moduleName && !value.startsWith(`${moduleName}.`)) {
+    throw new Error(`${kind}不属于模块 ${moduleName}：${value}`);
+  }
+}

package/template/packages/shared/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}

package/template/packages/storage/index.ts

@@ -6,6 +6,8 @@ export * from "./src/local-file-maintenance.js";
 export * from "./src/memory-blob-store.js";
 export * from "./src/in-memory-upload-repository.js";
 export * from "./src/upload-repository.js";
+export type { BoundCompletedUploadPurge } from "./src/upload-purge.js";
 export * from "./src/upload-service.js";
 export * from "./src/upload-streams.js";
 export * from "./src/upload-types.js";
+export { canonicalizeUploadIdentity } from "./src/upload-validation.js";

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/storage",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {