create-windy 0.2.19 → 0.2.21

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

@@ -0,0 +1,212 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AUDIT_ACTION_DEFINITIONS,
+  featureKey,
+  licenseVersionKey,
+  LICENSE_CATALOG,
+  type AuditActionRegistration,
+  type FeatureFlagDefinition,
+  type LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import {
+  composeAuditActionCatalog,
+  validateCapabilityCatalogs,
+} from "./catalog-validation.js";
+import type { ModuleManifest } from "./manifest.js";
+
+const customCatalog: LicenseCatalogDefinition[] = [
+  {
+    key: licenseVersionKey("oem-basic"),
+    label: "OEM 基础版",
+    description: "宿主定制基础版本。",
+    order: 10,
+  },
+  {
+    key: licenseVersionKey("oem-pro"),
+    label: "OEM 专业版",
+    description: "宿主定制专业版本。",
+    order: 20,
+  },
+];
+
+describe("validateCapabilityCatalogs License 版本目录", () => {
+  test("宿主自定义 catalog 下 manifest 引用未知版本时抛错", () => {
+    const manifest = moduleWithFeature(
+      feature("business.report", ["standard"]),
+    );
+
+    expect(() => validateCapabilityCatalogs([manifest], customCatalog)).toThrow(
+      "Feature business.report 引用了未知 License 版本：standard",
+    );
+  });
+
+  test("合法自定义 catalog 通过校验并作为快照目录返回", () => {
+    const manifest = moduleWithFeature(feature("business.report", ["oem-pro"]));
+
+    const catalogs = validateCapabilityCatalogs([manifest], customCatalog);
+
+    expect(catalogs.licenseVersions).toBe(customCatalog);
+  });
+
+  test("未传 catalog 时回退默认三级目录，保持向后兼容", () => {
+    const manifest = moduleWithFeature(
+      feature("business.report", ["standard"]),
+    );
+
+    const catalogs = validateCapabilityCatalogs([manifest]);
+
+    expect(catalogs.licenseVersions).toBe(LICENSE_CATALOG);
+  });
+
+  test("自定义 catalog 自身非法时快速报错", () => {
+    const manifest = moduleWithFeature(feature("business.report"));
+
+    expect(() =>
+      validateCapabilityCatalogs(
+        [manifest],
+        [customCatalog[0]!, customCatalog[0]!],
+      ),
+    ).toThrow("License 版本目录 Key 重复：oem-basic");
+  });
+});
+
+describe("Audit Action Catalog 开放注册", () => {
+  test("模块以定义对象贡献动作，聚合进目录且内置动作保留", () => {
+    const module = auditModule("ticket", [
+      {
+        key: "ticket.assign",
+        label: "工单指派",
+        description: "将工单指派给处理人。",
+      },
+    ]);
+
+    const catalog = composeAuditActionCatalog([module]);
+
+    expect(catalog).toContainEqual({
+      key: "ticket.assign",
+      label: "工单指派",
+      description: "将工单指派给处理人。",
+    });
+    for (const builtIn of AUDIT_ACTION_DEFINITIONS) {
+      expect(catalog).toContainEqual(builtIn);
+    }
+  });
+
+  test("目录输出结构符合 FoundationSnapshot 契约", () => {
+    const catalogs = validateCapabilityCatalogs([
+      auditModule("ticket", [
+        {
+          key: "ticket.assign",
+          label: "工单指派",
+          description: "将工单指派给处理人。",
+        },
+        "crud.create",
+      ]),
+    ]);
+
+    expect(catalogs.licenseVersions).toBe(LICENSE_CATALOG);
+    expect(catalogs.auditActions.length).toBe(
+      AUDIT_ACTION_DEFINITIONS.length + 1,
+    );
+    for (const definition of catalogs.auditActions) {
+      expect(typeof definition.key).toBe("string");
+      expect(definition.label.trim()).not.toBe("");
+      expect(definition.description.trim()).not.toBe("");
+    }
+    const keys = catalogs.auditActions.map(({ key }) => key);
+    expect(keys).toEqual([...keys].sort((a, b) => a.localeCompare(b)));
+  });
+
+  test("重复定义同一 Key 被拒绝", () => {
+    const first = auditModule("first", [
+      { key: "ticket.assign", label: "工单指派", description: "定义一。" },
+    ]);
+    const second = auditModule("second", [
+      { key: "ticket.assign", label: "工单指派", description: "定义二。" },
+    ]);
+    expect(() => composeAuditActionCatalog([first, second])).toThrow(
+      "审计动作定义重复：ticket.assign",
+    );
+
+    const override = auditModule("override", [
+      { key: "crud.create", label: "覆盖", description: "不允许。" },
+    ]);
+    expect(() => composeAuditActionCatalog([override])).toThrow(
+      "审计动作定义重复：crud.create",
+    );
+  });
+
+  test("引用未定义动作被拒绝", () => {
+    const module = auditModule("broken", ["ticket.assign"]);
+    expect(() => composeAuditActionCatalog([module])).toThrow(
+      "引用了未定义审计动作：ticket.assign",
+    );
+  });
+
+  test("定义对象的 Key、名称和说明不能为空", () => {
+    const module = auditModule("empty", [
+      { key: "ticket.assign", label: " ", description: "缺少名称。" },
+    ]);
+    expect(() => composeAuditActionCatalog([module])).toThrow(
+      "审计动作 Key、名称和说明不能为空",
+    );
+  });
+});
+
+function auditModule(
+  name: string,
+  auditActions: AuditActionRegistration[],
+): ModuleManifest {
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} module`,
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions,
+  };
+}
+
+function feature(
+  key: string,
+  allowedLicenseVersions?: string[],
+): FeatureFlagDefinition {
+  return {
+    key: featureKey(key),
+    label: key,
+    module: "business",
+    visible: "visible",
+    enabled: true,
+    stage: "stable",
+    allowedLicenseVersions: allowedLicenseVersions?.map(licenseVersionKey),
+  };
+}
+
+function moduleWithFeature(feature: FeatureFlagDefinition): ModuleManifest {
+  return {
+    name: "business",
+    version: "1.0.0",
+    label: "业务模块",
+    description: "测试用业务模块。",
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [feature],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+  };
+}

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

@@ -2,6 +2,9 @@ import {
   AUDIT_ACTION_DEFINITIONS,
   isAuditActionDefinition,
   LICENSE_CATALOG,
+  normalizeManifestBundles,
+  validateAndOrderBundles,
+  validateLicenseCatalog,
   type AuditActionDefinition,
   type FeatureFlagDefinition,
   type LicenseCatalogDefinition,
@@ -15,15 +18,29 @@ export interface PlatformCapabilityCatalogs {
 
 export function validateCapabilityCatalogs(
   modules: readonly ModuleManifest[],
+  licenseCatalog: readonly LicenseCatalogDefinition[] = LICENSE_CATALOG,
 ): PlatformCapabilityCatalogs {
   const auditActions = composeAuditActionCatalog(modules);
-  validateFeatureCatalog(modules, LICENSE_CATALOG);
+  validateLicenseCatalog(licenseCatalog);
+  validateFeatureCatalog(modules, licenseCatalog);
+  validateMigrationBundleCatalog(modules);
   return {
     auditActions,
-    licenseVersions: LICENSE_CATALOG,
+    licenseVersions: licenseCatalog,
   };
 }
 
+/**
+ * 启动期结构校验显式声明 migrationBundle 的模块；无 bundle 的旧式模块
+ * 由 drizzle 规范迁移管理，不参与模块级 Bundle 校验。
+ */
+export function validateMigrationBundleCatalog(
+  modules: readonly ModuleManifest[],
+): void {
+  const bundled = modules.filter((module) => module.migrationBundle);
+  validateAndOrderBundles(normalizeManifestBundles(bundled));
+}
+
 export function composeAuditActionCatalog(
   modules: readonly ModuleManifest[],
 ): AuditActionDefinition[] {

package/template/packages/modules/src/migration-bundle-validation.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type BundleMigrationDefinition,
+  type MigrationBundle,
+} from "@southwind-ai/shared";
+import {
+  validateCapabilityCatalogs,
+  validateMigrationBundleCatalog,
+} from "./catalog-validation.js";
+import type { ModuleManifest } from "./manifest.js";
+import { systemModuleFactories } from "./system-module-catalog.js";
+
+describe("Migration Bundle 启动校验", () => {
+  test("无 bundle 的旧式模块保持兼容", () => {
+    const legacy = fixture("system");
+    legacy.schemaExports = [
+      {
+        key: "system.database.schema",
+        exportName: "systemSchema",
+        migrationIds: ["0000..0028"],
+      },
+    ];
+
+    expect(() => validateCapabilityCatalogs([legacy])).not.toThrow();
+    expect(() =>
+      validateCapabilityCatalogs(
+        systemModuleFactories.map((factory) => factory()),
+      ),
+    ).not.toThrow();
+  });
+
+  test("合法 bundle 通过校验，跨模块依赖需显式声明", () => {
+    const base = bundledModule("base", [migration("base", "base.0001")]);
+    const feature = bundledModule(
+      "feature",
+      [migration("feature", "feature.0001", ["base.0001"])],
+      ["base"],
+    );
+
+    expect(() => validateMigrationBundleCatalog([feature, base])).not.toThrow();
+  });
+
+  test("重复 Migration ID 被拒绝", () => {
+    const first = bundledModule("first", [migration("first", "shared.0001")]);
+    const second = bundledModule("second", [
+      migration("second", "shared.0001"),
+    ]);
+
+    expect(() => validateMigrationBundleCatalog([first, second])).toThrow(
+      "Migration ID 重复：shared.0001",
+    );
+  });
+
+  test("缺少 checksum 被拒绝", () => {
+    const broken = bundledModule("broken", [
+      { ...migration("broken", "broken.0001"), checksum: "" },
+    ]);
+
+    expect(() => validateMigrationBundleCatalog([broken])).toThrow(
+      "Migration broken.0001 缺少 checksum",
+    );
+  });
+
+  test("非 semver 版本被拒绝", () => {
+    const broken = bundledModule("broken", [
+      migration("broken", "broken.0001"),
+    ]);
+    broken.version = "0.1";
+    broken.migrationBundle = { ...broken.migrationBundle!, version: "0.1" };
+
+    expect(() => validateMigrationBundleCatalog([broken])).toThrow(
+      "Migration Bundle broken 版本无效：0.1",
+    );
+  });
+
+  test("跨模块 Migration 依赖必须在 Bundle 中声明模块依赖", () => {
+    const base = bundledModule("base", [migration("base", "base.0001")]);
+    const feature = bundledModule("feature", [
+      migration("feature", "feature.0001", ["base.0001"]),
+    ]);
+
+    expect(() => validateMigrationBundleCatalog([base, feature])).toThrow(
+      "Migration feature.0001 跨模块依赖 base，但 Bundle 未声明该模块依赖",
+    );
+  });
+
+  test("模块依赖存在循环时被拒绝", () => {
+    const first = bundledModule(
+      "first",
+      [migration("first", "first.0001")],
+      ["second"],
+    );
+    const second = bundledModule(
+      "second",
+      [migration("second", "second.0001")],
+      ["first"],
+    );
+
+    expect(() => validateMigrationBundleCatalog([first, second])).toThrow(
+      "Migration Bundle 模块依赖存在循环",
+    );
+  });
+
+  test("单个 Bundle 内 Migration 顺序存在循环时被拒绝", () => {
+    const broken = bundledModule("broken", [
+      migration("broken", "broken.0001", ["broken.0002"]),
+      migration("broken", "broken.0002", ["broken.0001"]),
+    ]);
+
+    expect(() => validateMigrationBundleCatalog([broken])).toThrow(
+      "Migration Bundle broken 的迁移依赖存在循环",
+    );
+  });
+
+  test("Bundle 与 Manifest 声明不一致时被拒绝", () => {
+    const drift = bundledModule("drift", [migration("drift", "drift.0001")]);
+    drift.migrations = [];
+
+    expect(() => validateMigrationBundleCatalog([drift])).toThrow(
+      "Manifest drift 的 migrations 必须与 Migration Bundle 完全一致",
+    );
+
+    const versionDrift = bundledModule("version-drift", [
+      migration("version-drift", "version-drift.0001"),
+    ]);
+    versionDrift.migrationBundle = {
+      ...versionDrift.migrationBundle!,
+      version: "9.9.9",
+    };
+
+    expect(() => validateMigrationBundleCatalog([versionDrift])).toThrow(
+      "Migration Bundle version-drift 版本 9.9.9 与 Manifest 0.1.0 不一致",
+    );
+  });
+});
+
+function fixture(name: string): ModuleManifest {
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} module`,
+    menus: [],
+    adminRoutes: [],
+    permissions: [],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [],
+    providers: [],
+    auditActions: [],
+  };
+}
+
+function migration(
+  module: string,
+  id: string,
+  dependsOn: readonly string[] = [],
+): BundleMigrationDefinition {
+  return {
+    id,
+    module,
+    description: `${id} migration`,
+    direction: "up",
+    checksum: `sha256:${id}`,
+    dependsOn,
+    run: async () => {},
+  };
+}
+
+function bundledModule(
+  name: string,
+  migrations: BundleMigrationDefinition[],
+  dependencies: string[] = [],
+): ModuleManifest {
+  const manifest = fixture(name);
+  manifest.dependencies = dependencies;
+  manifest.migrations = [...migrations];
+  const bundle: MigrationBundle = {
+    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+    module: name,
+    version: manifest.version,
+    dependencies,
+    migrations,
+  };
+  manifest.migrationBundle = bundle;
+  return manifest;
+}

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

@@ -1,5 +1,58 @@
+export type { ModuleActor } from "./src/actor.js";
 export type {
+  ModuleAuditEmitter,
+  ModuleAuditEmitInput,
+  ModuleAuditTarget,
+} from "./src/audit-port.js";
+export type {
+  ModuleJobSubmitter,
+  ModuleJobSubmitInput,
+  ModuleJobSubmitResult,
+} from "./src/jobs-port.js";
+export type {
+  InstallableServerModule,
   ModuleHost,
   ModuleInitializer,
   ModuleUploadPolicy,
 } from "./src/module-host.js";
+export { requireModuleNamespace } from "./src/namespace.js";
+export type { ModuleRequestContext } from "./src/request-context.js";
+export type { ModuleRolePreset } from "./src/role-preset.js";
+export type {
+  ModuleRouteDefinition,
+  ModuleRouteHandler,
+  ModuleRouteMethod,
+} from "./src/route-definition.js";
+export type {
+  ModuleSearchContext,
+  ModuleSearchHealth,
+  ModuleSearchHit,
+  ModuleSearchPage,
+  ModuleSearchProvider,
+  ModuleSearchQuery,
+} from "./src/search-provider-port.js";
+export type {
+  ModuleStoragePort,
+  ModuleUploadSessionInput,
+} from "./src/storage-port.js";
+export type {
+  ModuleTaskHandler,
+  ModuleTaskHandlerRegistration,
+  ModuleTaskResult,
+} from "./src/task-registration.js";
+export type {
+  ModuleAgentToolHostPort,
+  ModuleAgentToolInvocation,
+  ModuleAgentToolResult,
+} from "./src/tool-host-port.js";
+export type {
+  ModuleToolContext,
+  ModuleToolHandlerRegistration,
+  ModuleToolResult,
+} from "./src/tool-registration.js";
+export type {
+  ModuleAiJsonValue,
+  ModuleAiOperationContext,
+  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationPlan,
+} from "./src/ai-operation-registration.js";

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

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -8,13 +8,28 @@
   },
   "files": [
     "index.ts",
-    "src/module-host.ts"
+    "src/actor.ts",
+    "src/ai-operation-registration.ts",
+    "src/audit-port.ts",
+    "src/jobs-port.ts",
+    "src/module-host.ts",
+    "src/namespace.ts",
+    "src/request-context.ts",
+    "src/role-preset.ts",
+    "src/route-definition.ts",
+    "src/search-provider-port.ts",
+    "src/storage-port.ts",
+    "src/task-registration.ts",
+    "src/tool-registration.ts",
+    "src/tool-host-port.ts"
   ],
   "scripts": {
+    "test": "bun test",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/jobs": "workspace:*"
+    "@southwind-ai/jobs": "workspace:*",
+    "@southwind-ai/storage": "workspace:*"
   },
   "exports": {
     ".": "./index.ts"

package/template/packages/server-sdk/src/actor.ts

@@ -0,0 +1,15 @@
+/**
+ * 当前操作者的只读视图，与 Server 现有 Actor 模型对齐。
+ *
+ * 视图只暴露身份、角色与权限；凭据状态、数据范围令牌等宿主内部字段不下发。
+ * 运行时对象由宿主颁发，模块不得自行构造或修改。
+ */
+export interface ModuleActor {
+  readonly id: string;
+  readonly type: "anonymous" | "user" | "service";
+  readonly name: string;
+  readonly username?: string;
+  readonly displayName?: string;
+  readonly roleCodes: readonly string[];
+  readonly permissionKeys: readonly string[];
+}

package/template/packages/server-sdk/src/ai-operation-registration.ts

@@ -0,0 +1,31 @@
+import type { ModuleActor } from "./actor.js";
+
+export type ModuleAiJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ModuleAiJsonValue[]
+  | { [key: string]: ModuleAiJsonValue };
+
+export interface ModuleAiOperationContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+/**
+ * 业务模块只负责把类型化输入收敛为模型无关的指令和用户消息。
+ * Provider、Deployment、Secret、Execution Grant 与 Tool 授权均由宿主持有。
+ */
+export interface ModuleAiOperationPlan {
+  readonly instructions: string;
+  readonly userPrompt: string;
+}
+
+export interface ModuleAiOperationHandlerRegistration {
+  readonly operationKey: string;
+  prepare(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+}

package/template/packages/server-sdk/src/audit-port.ts

@@ -0,0 +1,22 @@
+/**
+ * 模块审计事件的受控写入入口。
+ *
+ * 只允许 emit 本模块 Manifest `auditActions` 已注册的动作；越权动作在调用时抛错。
+ * 事件由宿主补齐 Actor、RequestId 与时间戳并写入统一 Audit Sink。
+ */
+export interface ModuleAuditTarget {
+  readonly type: string;
+  readonly id?: string;
+  readonly label?: string;
+}
+
+export interface ModuleAuditEmitInput {
+  readonly target?: ModuleAuditTarget;
+  readonly metadata?: Record<string, unknown>;
+  /** 关键事件走宿主 Critical 写入策略（写入失败会抛出）。 */
+  readonly critical?: boolean;
+}
+
+export interface ModuleAuditEmitter {
+  emit(action: string, input?: ModuleAuditEmitInput): Promise<void>;
+}

package/template/packages/server-sdk/src/jobs-port.ts

@@ -0,0 +1,24 @@
+/**
+ * 模块提交 Durable Job 的窄接口。
+ *
+ * 只能提交到本模块命名空间的 Handler；Queue 由宿主强制为模块命名空间，
+ * 提交人由宿主以当前 Actor 身份补齐，模块无法伪造。
+ */
+export interface ModuleJobSubmitInput {
+  readonly handlerKey: string;
+  readonly idempotencyKey: string;
+  readonly payload: Record<string, unknown>;
+  readonly priority?: number;
+  readonly maxAttempts?: number;
+  readonly timeoutSeconds?: number;
+  readonly availableAt?: Date;
+}
+
+export interface ModuleJobSubmitResult {
+  readonly jobId: string;
+  readonly created: boolean;
+}
+
+export interface ModuleJobSubmitter {
+  submit(input: ModuleJobSubmitInput): Promise<ModuleJobSubmitResult>;
+}