create-windy 0.2.7 → 0.2.8

package/template/packages/database/src/runner.test.ts

@@ -1,23 +1,20 @@
 import { describe, expect, test } from "bun:test";
-import type { ModuleManifest } from "@windy/modules";
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type MigrationBundle,
+  type MigrationManifestSource,
+} from "@southwind-ai/shared";
 import { PlatformMigrationRunner } from "./runner.js";
 import { InMemoryMigrationHistoryStore } from "./store.js";
 
 function moduleFixture(
   name: string,
   dependencies: string[] = [],
-): ModuleManifest {
+): MigrationManifestSource {
   return {
     name,
     version: "0.1.0",
-    label: name,
-    description: `${name} module`,
     dependencies,
-    menus: [],
-    adminRoutes: [],
-    permissions: [],
-    apiPermissions: [],
-    features: [],
     migrations: [
       {
         id: `${name}.001`,
@@ -32,10 +29,30 @@ function moduleFixture(
       },
     ],
     schemaExports: [],
-    tasks: [],
-    tools: [],
-    providers: [],
-    auditActions: [],
+  };
+}
+
+function bundleFixture(
+  module: string,
+  ids: readonly string[] = [`${module}.001`],
+  dependencies: readonly string[] = [],
+): MigrationBundle {
+  return {
+    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+    module,
+    version: "1.0.0",
+    dependencies,
+    migrations: ids.map((id, index) => ({
+      id,
+      module,
+      description: `migration ${index + 1}`,
+      direction: "up",
+      checksum: `sha256:${module}-${index + 1}`,
+      dependsOn: index === 0 ? [] : [ids[index - 1]],
+      async run(context) {
+        await context.execute({ sql: `select '${id}'` });
+      },
+    })),
   };
 }
 
@@ -93,4 +110,134 @@ describe("PlatformMigrationRunner", () => {
     expect(report.applied).toEqual(["audit.001"]);
     expect(executed).toEqual(["create table audit (id varchar(36))"]);
   });
+
+  test("fresh bundle 按模块与迁移依赖顺序执行并记录 checksum", async () => {
+    const store = new InMemoryMigrationHistoryStore();
+    const executed: string[] = [];
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store,
+      execute: async ({ sql }) => {
+        executed.push(sql);
+      },
+    });
+    const feature = bundleFixture(
+      "feature",
+      ["feature.002", "feature.001"],
+      ["system"],
+    );
+    feature.migrations[0].dependsOn = ["feature.001"];
+    feature.migrations[1].dependsOn = [];
+
+    const report = await runner.runBundles([feature, bundleFixture("system")]);
+
+    expect(report.applied).toEqual([
+      "system.001",
+      "feature.001",
+      "feature.002",
+    ]);
+    expect(executed).toEqual([
+      "select 'system.001'",
+      "select 'feature.001'",
+      "select 'feature.002'",
+    ]);
+    expect((await store.listApplied())[0]?.checksum).toBe("sha256:system-1");
+  });
+
+  test("repeat bundle 跳过 checksum 相同的已应用迁移", async () => {
+    const store = new InMemoryMigrationHistoryStore();
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store,
+    });
+    const bundle = bundleFixture("orders");
+
+    await runner.runBundles([bundle]);
+    const repeated = await runner.runBundles([bundle]);
+
+    expect(repeated.applied).toEqual([]);
+    expect(repeated.planned[0]).toMatchObject({
+      id: "orders.001",
+      checksum: "sha256:orders-1",
+      skipped: true,
+      skipReason: "already-applied",
+    });
+  });
+
+  test("执行失败后停止后续 migration", async () => {
+    const executed: string[] = [];
+    const bundle = bundleFixture("orders", [
+      "orders.001",
+      "orders.002",
+      "orders.003",
+    ]);
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store: new InMemoryMigrationHistoryStore(),
+      execute: async ({ sql }) => {
+        executed.push(sql);
+        if (sql.includes("002")) throw new Error("database unavailable");
+      },
+    });
+
+    const report = await runner.runBundles([bundle]);
+
+    expect(report.applied).toEqual(["orders.001"]);
+    expect(report.failed).toEqual([
+      { id: "orders.002", error: "database unavailable" },
+    ]);
+    expect(executed).toEqual(["select 'orders.001'", "select 'orders.002'"]);
+  });
+
+  test("拒绝错误模块归属和重复 migration id", async () => {
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store: new InMemoryMigrationHistoryStore(),
+    });
+    const wrongOwner = bundleFixture("orders");
+    wrongOwner.migrations[0].module = "billing";
+
+    await expect(runner.planBundles([wrongOwner])).rejects.toThrow(
+      "模块归属应为 orders",
+    );
+
+    const first = bundleFixture("orders", ["shared.001"]);
+    const second = bundleFixture("billing", ["shared.001"]);
+    await expect(runner.planBundles([first, second])).rejects.toThrow(
+      "Migration ID 重复：shared.001",
+    );
+  });
+
+  test("拒绝已应用 migration 的 checksum 漂移", async () => {
+    const store = new InMemoryMigrationHistoryStore();
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store,
+    });
+    const bundle = bundleFixture("orders");
+    await runner.runBundles([bundle]);
+    bundle.migrations[0].checksum = "sha256:changed";
+
+    await expect(runner.planBundles([bundle])).rejects.toThrow(
+      "checksum 与当前 Bundle 不一致",
+    );
+  });
+
+  test("Manifest schemaExports 只能引用所属 bundle migration", async () => {
+    const manifest = moduleFixture("orders");
+    manifest.schemaExports = [
+      {
+        key: "orders.schema",
+        migrationIds: ["orders.missing"],
+      },
+    ];
+    const runner = new PlatformMigrationRunner({
+      dialect: "postgresql",
+      store: new InMemoryMigrationHistoryStore(),
+    });
+
+    await expect(runner.plan([manifest])).rejects.toThrow(
+      "Bundle 中不存在的 Migration：orders.missing",
+    );
+  });
 });

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

@@ -1,11 +1,18 @@
-import type { MigrationDefinition, ModuleManifest } from "@windy/modules";
 import type {
+  BundleMigrationDefinition,
   DatabaseCompatibilityAdapter,
   DatabaseDialect,
+  MigrationBundle,
+  MigrationManifestSource,
   MigrationStatement,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
+import {
+  normalizeManifestBundles,
+  orderBundleMigrations,
+  validateAndOrderBundles,
+} from "./bundle-validation.js";
 import { createDialectAdapter } from "./dialects.js";
-import type { MigrationHistoryStore } from "./store.js";
+import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
 
 export interface MigrationRunnerOptions {
   dialect: DatabaseDialect;
@@ -19,8 +26,9 @@ export interface MigrationPlanItem {
   module: string;
   description: string;
   direction: "up" | "down";
+  checksum: string;
   skipped: boolean;
-  skipReason?: string;
+  skipReason?: "already-applied";
 }
 
 export interface MigrationRunReport {
@@ -47,45 +55,51 @@ export class PlatformMigrationRunner {
     this.now = options.now || (() => new Date());
   }
 
-  async plan(modules: ModuleManifest[]): Promise<MigrationPlanItem[]> {
-    const appliedIds = new Set(
-      (await this.options.store.listApplied()).map((entry) => entry.id),
-    );
+  async plan(modules: readonly MigrationManifestSource[]) {
+    return this.planBundles(normalizeManifestBundles(modules));
+  }
 
-    return sortModulesByDependency(modules).flatMap((module) =>
-      module.migrations.map((migration) => ({
-        id: migration.id,
-        module: migration.module,
-        description: migration.description,
-        direction: migration.direction,
-        skipped: appliedIds.has(migration.id),
-        skipReason: appliedIds.has(migration.id)
-          ? "already-applied"
-          : undefined,
-      })),
+  async planBundles(
+    bundles: readonly MigrationBundle[],
+  ): Promise<MigrationPlanItem[]> {
+    const ordered = validateAndOrderBundles(bundles);
+    const applied = appliedById(await this.options.store.listApplied());
+    return ordered.flatMap((bundle) =>
+      orderBundleMigrations(bundle).map((migration) =>
+        planItem(migration, applied.get(migration.id)),
+      ),
     );
   }
 
   async run(
-    modules: ModuleManifest[],
+    modules: readonly MigrationManifestSource[],
+    dryRun = false,
+  ): Promise<MigrationRunReport> {
+    return this.runBundles(normalizeManifestBundles(modules), dryRun);
+  }
+
+  async runBundles(
+    bundles: readonly MigrationBundle[],
     dryRun = false,
   ): Promise<MigrationRunReport> {
     const startedAt = this.now().toISOString();
-    const planned = await this.plan(modules);
-    const migrations = collectMigrations(modules);
+    const ordered = validateAndOrderBundles(bundles);
+    const planned = await this.planBundles(ordered);
+    const migrations = new Map(
+      ordered.flatMap((bundle) =>
+        bundle.migrations.map(
+          (migration) => [migration.id, migration] as const,
+        ),
+      ),
+    );
     const applied: string[] = [];
     const failed: Array<{ id: string; error: string }> = [];
     const statements: MigrationStatement[] = [];
 
     for (const item of planned) {
-      if (item.skipped) {
-        continue;
-      }
-
+      if (item.skipped) continue;
       const migration = migrations.get(item.id);
-      if (!migration) {
-        continue;
-      }
+      if (!migration) throw new Error(`Migration ${item.id} 不存在`);
 
       const stepStartedAt = this.now().toISOString();
       const stepStatements: MigrationStatement[] = [];
@@ -97,34 +111,19 @@ export class PlatformMigrationRunner {
           execute: async (statement) => {
             statements.push(statement);
             stepStatements.push(statement);
-            if (!dryRun) {
-              await this.executeStatement(statement);
-            }
+            if (!dryRun) await this.executeStatement(statement);
           },
         });
         applied.push(item.id);
-        await this.options.store.record({
-          id: item.id,
-          module: item.module,
-          direction: item.direction,
-          status: "applied",
-          startedAt: stepStartedAt,
-          finishedAt: this.now().toISOString(),
-          statements: stepStatements.map((statement) => statement.sql),
-        });
+        if (!dryRun) {
+          await this.recordResult(item, stepStartedAt, stepStatements);
+        }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         failed.push({ id: item.id, error: message });
-        await this.options.store.record({
-          id: item.id,
-          module: item.module,
-          direction: item.direction,
-          status: "failed",
-          startedAt: stepStartedAt,
-          finishedAt: this.now().toISOString(),
-          statements: stepStatements.map((statement) => statement.sql),
-          error: message,
-        });
+        if (!dryRun) {
+          await this.recordResult(item, stepStartedAt, stepStatements, message);
+        }
         break;
       }
     }
@@ -140,36 +139,55 @@ export class PlatformMigrationRunner {
       statements,
     };
   }
-}
 
-function collectMigrations(
-  modules: ModuleManifest[],
-): Map<string, MigrationDefinition> {
-  return new Map(
-    modules
-      .flatMap((module) => module.migrations)
-      .map((migration) => [migration.id, migration]),
-  );
+  private async recordResult(
+    item: MigrationPlanItem,
+    startedAt: string,
+    statements: readonly MigrationStatement[],
+    error?: string,
+  ): Promise<void> {
+    await this.options.store.record({
+      id: item.id,
+      module: item.module,
+      direction: item.direction,
+      status: error ? "failed" : "applied",
+      checksum: item.checksum,
+      startedAt,
+      finishedAt: this.now().toISOString(),
+      statements: statements.map(({ sql }) => sql),
+      error,
+    });
+  }
 }
 
-function sortModulesByDependency(modules: ModuleManifest[]): ModuleManifest[] {
-  const pending = new Map(modules.map((module) => [module.name, module]));
-  const sorted: ModuleManifest[] = [];
+function appliedById(entries: readonly MigrationHistoryEntry[]) {
+  return new Map(entries.map((entry) => [entry.id, entry]));
+}
 
-  while (pending.size > 0) {
-    const ready = Array.from(pending.values()).find((module) =>
-      (module.dependencies || []).every(
-        (dependency) => !pending.has(dependency),
-      ),
+function planItem(
+  migration: BundleMigrationDefinition,
+  applied: MigrationHistoryEntry | undefined,
+): MigrationPlanItem {
+  if (applied?.module !== undefined && applied.module !== migration.module) {
+    throw new Error(
+      `已应用 Migration ${migration.id} 归属 ${applied.module}，当前归属 ${migration.module}`,
     );
-
-    if (!ready) {
-      throw new Error("模块依赖存在循环，无法生成迁移计划");
-    }
-
-    sorted.push(ready);
-    pending.delete(ready.name);
   }
-
-  return sorted;
+  if (
+    applied?.checksum !== undefined &&
+    applied.checksum !== migration.checksum
+  ) {
+    throw new Error(
+      `已应用 Migration ${migration.id} checksum 与当前 Bundle 不一致`,
+    );
+  }
+  return {
+    id: migration.id,
+    module: migration.module,
+    description: migration.description,
+    direction: migration.direction,
+    checksum: migration.checksum,
+    skipped: Boolean(applied),
+    skipReason: applied ? "already-applied" : undefined,
+  };
 }

package/template/packages/database/src/schema/governed-exports.ts

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import type { LifecycleStatus } from "@windy/shared";
+import type { LifecycleStatus } from "@southwind-ai/shared";
 import {
   boolean,
   check,

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

@@ -12,7 +12,7 @@ import {
 } from "drizzle-orm/pg-core";
 import { sql } from "drizzle-orm";
 import { auditColumns, idColumn, statusColumn } from "./common.js";
-import type { CredentialState } from "@windy/shared";
+import type { CredentialState } from "@southwind-ai/shared";
 
 export const departments = pgTable(
   "departments",

package/template/packages/database/src/schema/license-v1.ts

@@ -1,4 +1,4 @@
-import type { LicenseV1Claims, LicenseVersionKey } from "@windy/shared";
+import type { LicenseV1Claims, LicenseVersionKey } from "@southwind-ai/shared";
 import { sql } from "drizzle-orm";
 import {
   check,

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

@@ -8,7 +8,7 @@ import {
   uniqueIndex,
   varchar,
 } from "drizzle-orm/pg-core";
-import type { TargetRef } from "@windy/shared";
+import type { TargetRef } from "@southwind-ai/shared";
 import { auditColumns, idColumn, statusColumn } from "./common.js";
 import { users } from "./identity.js";
 

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";