create-windy 0.2.6 → 0.2.8

package/template/packages/database/src/schema/platform-settings.ts

@@ -2,7 +2,7 @@
 export {};
 
 // @windy-module system.configuration begin
-import type { ModuleConfigDiffEntry, ModuleConfigValues } from "@windy/shared";
+import type { ModuleConfigDiffEntry, ModuleConfigValues } from "@southwind-ai/shared";
 import {
   index,
   integer,

package/template/packages/database/src/schema/workflow.ts

@@ -10,7 +10,7 @@ import {
   uniqueIndex,
   varchar,
 } from "drizzle-orm/pg-core";
-import type { CandidateRole, TargetRef, WorkItem } from "@windy/shared";
+import type { CandidateRole, TargetRef, WorkItem } from "@southwind-ai/shared";
 
 export const workflowWorkItems = pgTable(
   "workflow_work_items",

package/template/packages/database/src/sql-store.ts

@@ -1,4 +1,4 @@
-import type { MigrationStatement } from "@windy/shared";
+import type { MigrationStatement } from "@southwind-ai/shared";
 import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
 
 export interface QueryResult<Row> {

package/template/packages/database/src/store.ts

@@ -1,4 +1,4 @@
-import type { ISODateTime } from "@windy/shared";
+import type { ISODateTime } from "@southwind-ai/shared";
 
 export type MigrationStatus = "applied" | "failed";
 

package/template/packages/example-work-order/index.ts

@@ -1,3 +1,4 @@
 export * from "./src/contract.js";
 export * from "./src/manifest.js";
+export * from "./src/migration-bundle.js";
 export * from "./src/schema.js";

package/template/packages/example-work-order/package.json

@@ -1,13 +1,14 @@
 {
-  "name": "@windy/example-work-order",
+  "name": "@southwind-ai/example-work-order",
   "version": "0.1.0",
   "private": true,
   "type": "module",
   "dependencies": {
-    "@windy/shared": "workspace:*",
+    "@southwind-ai/shared": "workspace:*",
     "zod": "^4.4.3"
   },
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./migration-bundle": "./src/migration-bundle.ts"
   }
 }

package/template/packages/example-work-order/src/contract.ts

@@ -2,7 +2,7 @@ import type {
   EntityAuditFields,
   LifecycleStatus,
   PageResult,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
 
 export const workOrderPriorities = ["low", "medium", "high"] as const;
 export const workOrderWorkflowStatuses = [

package/template/packages/example-work-order/src/manifest.ts

@@ -2,7 +2,11 @@ import {
   defineSearchProvider,
   featureKey,
   licenseVersionKey,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
+import {
+  WORK_ORDER_INITIAL_MIGRATION_ID,
+  workOrderMigrationBundle,
+} from "./migration-bundle.js";
 
 const FEATURE_KEY = featureKey("work-order.ticket");
 
@@ -41,12 +45,13 @@ export function workOrderModule() {
         ],
       },
     ],
-    migrations: [],
+    migrations: [...workOrderMigrationBundle.migrations],
+    migrationBundle: workOrderMigrationBundle,
     schemaExports: [
       {
         key: "work-order.database.schema",
         exportName: "workOrders",
-        migrationIds: ["0018_cheerful_alex_power"],
+        migrationIds: [WORK_ORDER_INITIAL_MIGRATION_ID],
       },
     ],
     tasks: [

package/template/packages/example-work-order/src/migration-bundle.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  DatabaseCompatibilityAdapter,
+  MigrationStatement,
+} from "@southwind-ai/shared";
+import { workOrderModule } from "./manifest.js";
+import {
+  WORK_ORDER_INITIAL_MIGRATION_ID,
+  workOrderMigrationBundle,
+} from "./migration-bundle.js";
+
+describe("示例工单 Migration Bundle", () => {
+  test("业务包自持 bundle 并与 Manifest Schema Export 闭环", () => {
+    const manifest = workOrderModule();
+
+    expect(manifest.migrationBundle).toBe(workOrderMigrationBundle);
+    expect(manifest.migrations.map(({ id }) => id)).toEqual([
+      WORK_ORDER_INITIAL_MIGRATION_ID,
+    ]);
+    expect(manifest.schemaExports[0]?.migrationIds).toEqual([
+      WORK_ORDER_INITIAL_MIGRATION_ID,
+    ]);
+  });
+
+  test("安装 SQL 只包含 work_orders 表与索引且使用幂等建表", async () => {
+    const statements: MigrationStatement[] = [];
+    await workOrderMigrationBundle.migrations[0].run({
+      dialect: "postgresql",
+      dryRun: true,
+      adapter: {} as DatabaseCompatibilityAdapter,
+      execute(statement) {
+        statements.push(statement);
+        return Promise.resolve();
+      },
+    });
+    const sql = statements.map(({ sql: statement }) => statement).join("\n");
+
+    expect(sql).toContain("create table if not exists work_orders");
+    expect(sql).toContain("create index if not exists idx_work_orders_owner");
+    expect(sql).not.toContain("feature_flags");
+    expect(sql).not.toContain("license");
+  });
+});

package/template/packages/example-work-order/src/migration-bundle.ts

@@ -0,0 +1,64 @@
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type MigrationBundle,
+  type MigrationExecutionContext,
+} from "@southwind-ai/shared";
+
+export const WORK_ORDER_INITIAL_MIGRATION_ID =
+  "work-order.0001.create-work-orders";
+
+export const workOrderMigrationBundle: MigrationBundle = {
+  formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+  module: "work-order",
+  version: "0.1.0",
+  migrations: [
+    {
+      id: WORK_ORDER_INITIAL_MIGRATION_ID,
+      module: "work-order",
+      description: "创建示例工单表及查询索引",
+      direction: "up",
+      checksum:
+        "sha256:cb97709a8680fabf46bff40e33d29e12255969bb54d232d7ea633324dc77ce33",
+      async run(context) {
+        for (const statement of workOrderStatements(context)) {
+          await context.execute({ sql: statement });
+        }
+      },
+    },
+  ],
+};
+
+function workOrderStatements(context: MigrationExecutionContext): string[] {
+  const timestamp =
+    context.dialect === "mysql" ? "datetime" : "timestamp with time zone";
+  const createTable = `create table if not exists work_orders (
+  id varchar(64) primary key not null,
+  title varchar(120) not null,
+  description text not null,
+  priority varchar(24) not null,
+  workflow_status varchar(32) not null,
+  owner_id varchar(64) not null,
+  department_id varchar(64),
+  status varchar(32) not null,
+  created_at ${timestamp} default current_timestamp not null,
+  created_by varchar(64) not null,
+  updated_at ${timestamp} default current_timestamp not null,
+  updated_by varchar(64) not null,
+  deleted_at ${timestamp},
+  deleted_by varchar(64)
+)`;
+  const optionalClause =
+    context.dialect === "postgresql" || context.dialect === "kingbase"
+      ? " if not exists"
+      : "";
+  const indexes = [
+    ["idx_work_orders_owner", "owner_id"],
+    ["idx_work_orders_department", "department_id"],
+    ["idx_work_orders_status", "status"],
+    ["idx_work_orders_workflow", "workflow_status"],
+  ].map(
+    ([name, column]) =>
+      `create index${optionalClause} ${name} on work_orders (${column})`,
+  );
+  return [createTable, ...indexes];
+}

package/template/packages/jobs/index.ts

@@ -0,0 +1,2 @@
+export * from "./src/handlers.js";
+export * from "./src/types.js";

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]),
   );