create-windy 0.2.7 → 0.2.8

package/template/packages/jobs/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@southwind-ai/jobs",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/handlers.ts",
+    "src/types.ts"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@southwind-ai/storage": "workspace:*"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./handlers": "./src/handlers.ts",
+    "./types": "./src/types.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/packages/jobs/src/handlers.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  DurableHandlerError,
+  DurableHandlerRegistry,
+  type DurableHandlerContext,
+} from "./handlers.js";
+
+describe("DurableHandlerRegistry", () => {
+  test("解析 payload 后执行已注册 handler", async () => {
+    const received: string[] = [];
+    const registry = new DurableHandlerRegistry().register({
+      key: "example.report.generate",
+      payload: {
+        parse(input) {
+          if (
+            typeof input !== "object" ||
+            input === null ||
+            !("reportId" in input) ||
+            typeof input.reportId !== "string"
+          ) {
+            throw new DurableHandlerError(
+              "INVALID_PAYLOAD",
+              "reportId 无效",
+              false,
+            );
+          }
+          return { reportId: input.reportId };
+        },
+      },
+      execute(payload) {
+        received.push(payload.reportId);
+      },
+    });
+
+    await registry
+      .get("example.report.generate")
+      ?.execute({ reportId: "report-1" }, createContext());
+
+    expect(received).toEqual(["report-1"]);
+    expect(registry.keys()).toEqual(["example.report.generate"]);
+  });
+
+  test("拒绝空 key 和重复注册", () => {
+    const registry = new DurableHandlerRegistry();
+    const definition = {
+      key: "example.sync",
+      payload: { parse: () => ({}) },
+      execute: () => undefined,
+    };
+
+    expect(() => registry.register({ ...definition, key: " " })).toThrow(
+      "任务 handler key 不能为空",
+    );
+    registry.register(definition);
+    expect(() => registry.register(definition)).toThrow(
+      "任务 handler 重复注册：example.sync",
+    );
+  });
+});
+
+function createContext(): DurableHandlerContext {
+  return {
+    jobId: "job-1",
+    stageKey: "main",
+    attemptNumber: 1,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}

package/template/{apps/server/src/jobs/handler-registry.ts → packages/jobs/src/handlers.ts}

@@ -1,4 +1,4 @@
-import type { ArtifactRef } from "@windy/storage";
+import type { ArtifactRef } from "@southwind-ai/storage";
 
 export interface PayloadParser<T> {
   parse(input: unknown): T;
@@ -45,7 +45,7 @@ export interface RegisteredDurableHandler {
 export class DurableHandlerRegistry {
   private readonly handlers = new Map<string, RegisteredDurableHandler>();
 
-  register<T>(definition: DurableHandlerDefinition<T>) {
+  register<T>(definition: DurableHandlerDefinition<T>): this {
     if (!definition.key.trim()) throw new Error("任务 handler key 不能为空");
     if (this.handlers.has(definition.key)) {
       throw new Error(`任务 handler 重复注册：${definition.key}`);
@@ -59,11 +59,11 @@ export class DurableHandlerRegistry {
     return this;
   }
 
-  get(key: string) {
+  get(key: string): RegisteredDurableHandler | undefined {
     return this.handlers.get(key);
   }
 
-  keys() {
+  keys(): string[] {
     return [...this.handlers.keys()].sort();
   }
 }

package/template/{apps/server/src/jobs → packages/jobs/src}/types.ts

@@ -1,4 +1,4 @@
-import type { ArtifactRef } from "@windy/storage";
+import type { ArtifactRef } from "@southwind-ai/storage";
 
 export type DurableJobStatus =
   | "queued"
@@ -178,3 +178,9 @@ export interface SubmitDurableJobResult {
   job: DurableJob;
   created: boolean;
 }
+
+export interface DurableJobs {
+  submit(input: SubmitDurableJob): Promise<SubmitDurableJobResult>;
+  get(id: string): Promise<DurableJobSnapshot | undefined>;
+  list(requestedBy: string, limit?: number): Promise<DurableJob[]>;
+}

package/template/packages/{license-sdk → jobs}/tsconfig.json

@@ -7,7 +7,6 @@
     "strict": true,
     "noImplicitAny": true,
     "esModuleInterop": true,
-    "resolveJsonModule": true,
     "skipLibCheck": true,
     "outDir": "dist",
     "types": ["bun"]

package/template/packages/modules/index.ts

@@ -1,8 +1,8 @@
 export * from "./src/manifest.js";
 export * from "./src/composition.js";
+export * from "./src/catalog-validation.js";
 export * from "./src/menu-composition.js";
 export * from "./src/registry.js";
 export * from "./src/system-modules.js";
 export * from "./src/system-module-catalog.js";
 export * from "./src/system-api-permissions.js";
-export * from "./src/installed-business-modules.js";

package/template/packages/modules/package.json

@@ -1,13 +1,23 @@
 {
-  "name": "@windy/modules",
-  "version": "0.1.0",
-  "private": true,
+  "name": "@southwind-ai/modules",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
   "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
   "dependencies": {
-    "@windy/example-work-order": "workspace:*",
-    "@windy/shared": "workspace:*"
+    "@southwind-ai/shared": "workspace:*"
   },
   "exports": {
     ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/template/packages/modules/src/catalog-validation.ts

@@ -0,0 +1,123 @@
+import {
+  AUDIT_ACTION_DEFINITIONS,
+  isAuditActionDefinition,
+  LICENSE_CATALOG,
+  type AuditActionDefinition,
+  type FeatureFlagDefinition,
+  type LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+export interface PlatformCapabilityCatalogs {
+  auditActions: readonly AuditActionDefinition[];
+  licenseVersions: readonly LicenseCatalogDefinition[];
+}
+
+export function validateCapabilityCatalogs(
+  modules: readonly ModuleManifest[],
+): PlatformCapabilityCatalogs {
+  const auditActions = composeAuditActionCatalog(modules);
+  validateFeatureCatalog(modules, LICENSE_CATALOG);
+  return {
+    auditActions,
+    licenseVersions: LICENSE_CATALOG,
+  };
+}
+
+export function composeAuditActionCatalog(
+  modules: readonly ModuleManifest[],
+): AuditActionDefinition[] {
+  const definitions = new Map<string, AuditActionDefinition>(
+    AUDIT_ACTION_DEFINITIONS.map((definition) => [
+      definition.key,
+      { ...definition },
+    ]),
+  );
+  const registrations = modules.flatMap((module) => module.auditActions);
+
+  for (const registration of registrations) {
+    if (!isAuditActionDefinition(registration)) continue;
+    validateAuditDefinition(registration);
+    if (definitions.has(registration.key)) {
+      throw new Error(`审计动作定义重复：${registration.key}`);
+    }
+    definitions.set(registration.key, { ...registration });
+  }
+
+  for (const registration of registrations) {
+    const key =
+      typeof registration === "string" ? registration : registration.key;
+    if (!definitions.has(key)) {
+      throw new Error(`引用了未定义审计动作：${key}`);
+    }
+  }
+
+  return [...definitions.values()].sort((left, right) =>
+    left.key.localeCompare(right.key),
+  );
+}
+
+export function validateFeatureCatalog(
+  modules: readonly ModuleManifest[],
+  licenseCatalog: readonly LicenseCatalogDefinition[],
+): void {
+  const features = modules.flatMap((module) => module.features);
+  const byKey = new Map(features.map((feature) => [feature.key, feature]));
+  const licenseKeys = new Set(licenseCatalog.map(({ key }) => key));
+
+  for (const feature of features) {
+    for (const dependency of feature.dependencies || []) {
+      if (dependency === feature.key) {
+        throw new Error(`Feature ${feature.key} 不能依赖自身`);
+      }
+      if (!byKey.has(dependency)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未注册依赖：${dependency}`,
+        );
+      }
+    }
+    for (const version of feature.allowedLicenseVersions || []) {
+      if (!licenseKeys.has(version)) {
+        throw new Error(
+          `Feature ${feature.key} 引用了未知 License 版本：${version}`,
+        );
+      }
+    }
+  }
+
+  validateFeatureCycles(features, byKey);
+}
+
+function validateAuditDefinition(definition: AuditActionDefinition): void {
+  if (
+    !definition.key.trim() ||
+    !definition.label.trim() ||
+    !definition.description.trim()
+  ) {
+    throw new Error("审计动作 Key、名称和说明不能为空");
+  }
+}
+
+function validateFeatureCycles(
+  features: readonly FeatureFlagDefinition[],
+  byKey: ReadonlyMap<string, FeatureFlagDefinition>,
+): void {
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+
+  const visit = (feature: FeatureFlagDefinition): void => {
+    if (visited.has(feature.key)) return;
+    if (visiting.has(feature.key)) {
+      throw new Error(`Feature 依赖存在循环：${feature.key}`);
+    }
+    visiting.add(feature.key);
+    for (const dependency of feature.dependencies || []) {
+      const target = byKey.get(dependency);
+      if (target) visit(target);
+    }
+    visiting.delete(feature.key);
+    visited.add(feature.key);
+  };
+
+  for (const feature of features) visit(feature);
+}

package/template/packages/modules/src/composition.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { featureKey } from "@windy/shared";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 import { validateModuleComposition } from "./composition.js";
 
@@ -50,10 +50,83 @@ describe("Module Composition 契约", () => {
     );
 
     const audit = fixture("audit");
-    audit.tools[0]!.auditAction = "security.denied";
+    audit.tools[0]!.auditAction = "audit.unknown";
     expect(() => validateModuleComposition([audit])).toThrow("未注册审计动作");
   });
 
+  test("业务模块可注册带展示信息的审计动作目录", () => {
+    const module = fixture("ticket");
+    module.auditActions.push({
+      key: "ticket.assign",
+      label: "工单指派",
+      description: "将工单指派给处理人。",
+    });
+    module.tools[0]!.auditAction = "ticket.assign";
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    const unknown = fixture("unknown");
+    unknown.auditActions.push("unknown.action");
+    expect(() => validateModuleComposition([unknown])).toThrow(
+      "引用了未定义审计动作",
+    );
+  });
+
+  test("审计动作定义不可覆盖平台动作或重复注册", () => {
+    const platform = fixture("platform");
+    platform.auditActions.push({
+      key: "crud.create",
+      label: "覆盖动作",
+      description: "不允许覆盖平台定义。",
+    });
+    expect(() => validateModuleComposition([platform])).toThrow(
+      "审计动作定义重复：crud.create",
+    );
+
+    const first = fixture("first");
+    const second = fixture("second");
+    for (const module of [first, second]) {
+      module.auditActions.push({
+        key: "ticket.assign",
+        label: "工单指派",
+        description: "将工单指派给处理人。",
+      });
+    }
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "审计动作定义重复：ticket.assign",
+    );
+  });
+
+  test("Feature 依赖未知、自依赖和循环时 fail-fast", () => {
+    const unknown = fixture("unknown");
+    unknown.features[0]!.dependencies = [featureKey("missing.feature")];
+    expect(() => validateModuleComposition([unknown])).toThrow(
+      "引用了未注册依赖",
+    );
+
+    const self = fixture("self");
+    self.features[0]!.dependencies = [featureKey("self.feature")];
+    expect(() => validateModuleComposition([self])).toThrow("不能依赖自身");
+
+    const first = fixture("first");
+    const second = fixture("second");
+    first.features[0]!.dependencies = [featureKey("second.feature")];
+    second.features[0]!.dependencies = [featureKey("first.feature")];
+    expect(() => validateModuleComposition([first, second])).toThrow(
+      "Feature 依赖存在循环",
+    );
+  });
+
+  test("Feature 只能引用 License Catalog 中的版本", () => {
+    const module = fixture("license");
+    module.features[0]!.allowedLicenseVersions = [
+      licenseVersionKey("enterprise"),
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "引用了未知 License 版本：enterprise",
+    );
+  });
+
   test("菜单 Guard 必须与 Admin Route 一致", () => {
     const module = fixture("system");
     module.adminRoutes[0]!.permissionKey = "system.manage";

package/template/packages/modules/src/composition.ts

@@ -1,9 +1,10 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 import type {
   ModuleImplementationBindings,
   ModuleManifest,
 } from "./manifest.js";
 import { composeModuleMenus } from "./menu-composition.js";
+import { validateCapabilityCatalogs } from "./catalog-validation.js";
 
 export interface ValidatedModuleComposition {
   modules: readonly ModuleManifest[];
@@ -31,7 +32,8 @@ export function validateModuleComposition(
     "Feature",
     modules.flatMap((module) => module.features.map(({ key }) => key)),
   );
-  const audits = new Set(modules.flatMap((module) => module.auditActions));
+  const catalogs = validateCapabilityCatalogs(modules);
+  const audits = new Set(catalogs.auditActions.map(({ key }) => key));
   const menus = composeModuleMenus(modules).flatMap((menu) =>
     flattenMenus([menu]),
   );

package/template/packages/modules/src/manifest.ts

@@ -1,23 +1,17 @@
 import type {
   ApiPermissionBinding,
+  AuditActionRegistration,
   AuditActionType,
   DataGovernancePolicyDefinition,
   FeatureFlagDefinition,
-  MigrationExecutionContext,
+  MigrationBundle,
+  MigrationDefinition,
   MenuNode,
   PermissionDefinition,
   SearchProviderManifestDefinition,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
 
-export type MigrationDirection = "up" | "down";
-
-export interface MigrationDefinition {
-  id: string;
-  module: string;
-  description: string;
-  direction: MigrationDirection;
-  run(context: MigrationExecutionContext): Promise<void>;
-}
+export type { MigrationDefinition, MigrationDirection } from "@southwind-ai/shared";
 
 export interface ModuleToolDefinition {
   key: string;
@@ -77,12 +71,13 @@ export interface ModuleManifest {
   apiPermissions: ApiPermissionBinding[];
   features: FeatureFlagDefinition[];
   migrations: MigrationDefinition[];
+  migrationBundle?: MigrationBundle;
   schemaExports: ModuleSchemaExportDefinition[];
   tasks: ModuleScheduledTaskDefinition[];
   tools: ModuleToolDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
   dataPolicies?: DataGovernancePolicyDefinition[];
-  auditActions: AuditActionType[];
+  auditActions: AuditActionRegistration[];
   metadata?: Record<string, unknown>;
 }
 

package/template/packages/modules/src/menu-composition.ts

@@ -1,4 +1,4 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 
 export function composeModuleMenus(

package/template/packages/modules/src/system-api-binding.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding, HttpMethod } from "@windy/shared";
+import type { ApiPermissionBinding, HttpMethod } from "@southwind-ai/shared";
 
 interface ResourceBindingInput {
   path: string;

package/template/packages/modules/src/system-api-data-governance.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
 import { governedUserExportBindings } from "./system-governed-export-bindings.js";
 

package/template/packages/modules/src/system-api-permissions.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding, resourceBindings } from "./system-api-binding.js";
 // @windy-module system.data-governance begin
 import { dataGovernanceApiPermissionBindings } from "./system-api-data-governance.js";

package/template/packages/modules/src/system-data-governance.ts

@@ -1,4 +1,4 @@
-import { featureKey, type DataGovernancePolicyDefinition } from "@windy/shared";
+import { featureKey, type DataGovernancePolicyDefinition } from "@southwind-ai/shared";
 
 export const systemDataPolicies: DataGovernancePolicyDefinition[] = [
   {

package/template/packages/modules/src/system-features.ts

@@ -1,4 +1,4 @@
-import { featureKey, licenseVersionKey } from "@windy/shared";
+import { featureKey, licenseVersionKey } from "@southwind-ai/shared";
 import type { ModuleManifest } from "./manifest.js";
 
 // @windy-module system.scheduler begin

package/template/packages/modules/src/system-governed-export-bindings.ts

@@ -1,4 +1,4 @@
-import type { ApiPermissionBinding } from "@windy/shared";
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
 
 export function governedUserExportBindings(): ApiPermissionBinding[] {

package/template/packages/modules/src/system-module-catalog.ts

@@ -1,4 +1,4 @@
-import type { MenuNode } from "@windy/shared";
+import type { MenuNode } from "@southwind-ai/shared";
 import type { ModuleFactory, ModuleManifest } from "./manifest.js";
 import { systemFoundationModule } from "./system-modules.js";
 

package/template/packages/server-sdk/index.ts

@@ -0,0 +1,5 @@
+export type {
+  ModuleHost,
+  ModuleInitializer,
+  ModuleUploadPolicy,
+} from "./src/module-host.js";

package/template/packages/server-sdk/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@southwind-ai/server-sdk",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/module-host.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "dependencies": {
+    "@southwind-ai/jobs": "workspace:*"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/packages/server-sdk/src/module-host.ts

@@ -0,0 +1,29 @@
+import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+
+export interface ModuleUploadPolicy {
+  purpose: string;
+  maxByteSize: number;
+  maxPartByteSize: number;
+  sessionTtlMs: number;
+  allowedTypes: Readonly<Record<string, readonly string[]>>;
+  signature?: "image" | "none";
+}
+
+/**
+ * 模块作用域 Host。注册的任务 Key 与上传用途必须使用初始化器模块名作为命名空间。
+ */
+export interface ModuleHost {
+  readonly moduleName: string;
+  registerUploadPolicy(policy: ModuleUploadPolicy): void;
+  registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
+}
+
+/**
+ * 已安装模块的 Server 初始化入口。
+ *
+ * 初始化器在 Storage 与 Durable Job 运行时创建前顺序执行；这里只注册定义，不启动 Worker。
+ */
+export interface ModuleInitializer {
+  readonly moduleName: string;
+  initialize(host: ModuleHost): Promise<void> | void;
+}

package/template/packages/server-sdk/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"]
+}

package/template/packages/shared/index.ts

@@ -3,6 +3,8 @@ export * from "./src/database.js";
 export * from "./src/data-governance.js";
 export * from "./src/feature.js";
 export * from "./src/license.js";
+export * from "./src/license-catalog.js";
+export * from "./src/migration.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
 export * from "./src/notification.js";

package/template/packages/shared/package.json

@@ -1,9 +1,20 @@
 {
-  "name": "@windy/shared",
-  "version": "0.1.0",
-  "private": true,
+  "name": "@southwind-ai/shared",
+  "version": "0.1.1",
+  "license": "UNLICENSED",
   "type": "module",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
   "exports": {
     ".": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }