create-windy 0.2.6 → 0.2.8

package/template/packages/database/src/bundle-validation.ts

@@ -0,0 +1,218 @@
+import {
+  MIGRATION_BUNDLE_FORMAT_VERSION,
+  type BundleMigrationDefinition,
+  type MigrationBundle,
+  type MigrationDefinition,
+  type MigrationManifestSource,
+} from "@southwind-ai/shared";
+
+export function normalizeManifestBundles(
+  modules: readonly MigrationManifestSource[],
+): MigrationBundle[] {
+  return modules.map((manifest) => {
+    const bundle =
+      manifest.migrationBundle ||
+      legacyManifestBundle(manifest, manifest.migrations);
+    if (bundle.module !== manifest.name) {
+      throw new Error(
+        `Migration Bundle ${bundle.module} 与 Manifest ${manifest.name} 不一致`,
+      );
+    }
+    if (bundle.version !== manifest.version) {
+      throw new Error(
+        `Migration Bundle ${bundle.module} 版本 ${bundle.version} 与 Manifest ${manifest.version} 不一致`,
+      );
+    }
+    assertSameDependencies(manifest, bundle);
+    assertSameMigrations(manifest, bundle);
+    assertSchemaMigrationReferences(manifest, bundle);
+    return bundle;
+  });
+}
+
+function assertSameDependencies(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const declared = manifest.dependencies || [];
+  const bundled = bundle.dependencies || [];
+  if (
+    declared.length !== bundled.length ||
+    declared.some((dependency) => !bundled.includes(dependency))
+  ) {
+    throw new Error(
+      `Manifest ${manifest.name} 的 dependencies 必须与 Migration Bundle 一致`,
+    );
+  }
+}
+
+function legacyManifestBundle(
+  manifest: MigrationManifestSource,
+  migrations: readonly MigrationDefinition[],
+): MigrationBundle {
+  return {
+    formatVersion: MIGRATION_BUNDLE_FORMAT_VERSION,
+    module: manifest.name,
+    version: manifest.version,
+    dependencies: manifest.dependencies,
+    migrations: migrations.map((migration) => ({
+      ...migration,
+      checksum:
+        migration.checksum ||
+        `legacy:${manifest.name}:${manifest.version}:${migration.id}`,
+    })),
+  };
+}
+
+function assertSameMigrations(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const declared = manifest.migrations.map(({ id }) => id);
+  const bundled = bundle.migrations.map(({ id }) => id);
+  if (
+    declared.length !== bundled.length ||
+    declared.some((id, index) => id !== bundled[index])
+  ) {
+    throw new Error(
+      `Manifest ${manifest.name} 的 migrations 必须与 Migration Bundle 完全一致`,
+    );
+  }
+}
+
+function assertSchemaMigrationReferences(
+  manifest: MigrationManifestSource,
+  bundle: MigrationBundle,
+): void {
+  const ids = new Set(bundle.migrations.map(({ id }) => id));
+  for (const schema of manifest.schemaExports || []) {
+    for (const migrationId of schema.migrationIds) {
+      if (!ids.has(migrationId)) {
+        throw new Error(
+          `Schema Export ${schema.key} 引用了 Bundle 中不存在的 Migration：${migrationId}`,
+        );
+      }
+    }
+  }
+}
+
+export function validateAndOrderBundles(
+  bundles: readonly MigrationBundle[],
+): MigrationBundle[] {
+  const byModule = new Map<string, MigrationBundle>();
+  const migrationOwner = new Map<string, string>();
+  for (const bundle of bundles) {
+    validateBundle(bundle);
+    if (byModule.has(bundle.module)) {
+      throw new Error(`Migration Bundle 模块重复：${bundle.module}`);
+    }
+    byModule.set(bundle.module, bundle);
+    for (const migration of bundle.migrations) {
+      const owner = migrationOwner.get(migration.id);
+      if (owner) {
+        throw new Error(
+          `Migration ID 重复：${migration.id}（${owner} / ${bundle.module}）`,
+        );
+      }
+      migrationOwner.set(migration.id, bundle.module);
+    }
+  }
+  for (const bundle of bundles) {
+    for (const dependency of bundle.dependencies || []) {
+      if (!byModule.has(dependency)) {
+        throw new Error(
+          `Migration Bundle ${bundle.module} 依赖未安装模块：${dependency}`,
+        );
+      }
+    }
+    validateMigrationDependencies(bundle, migrationOwner);
+  }
+  return topologicalBundles(byModule);
+}
+
+function validateBundle(bundle: MigrationBundle): void {
+  if (bundle.formatVersion !== MIGRATION_BUNDLE_FORMAT_VERSION) {
+    throw new Error(
+      `Migration Bundle ${bundle.module} 格式版本不受支持：${bundle.formatVersion}`,
+    );
+  }
+  if (!bundle.module.trim()) throw new Error("Migration Bundle 缺少 module");
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(bundle.version)) {
+    throw new Error(
+      `Migration Bundle ${bundle.module} 版本无效：${bundle.version}`,
+    );
+  }
+  for (const migration of bundle.migrations) {
+    if (migration.module !== bundle.module) {
+      throw new Error(
+        `Migration ${migration.id} 的模块归属应为 ${bundle.module}`,
+      );
+    }
+    if (!migration.id.trim()) throw new Error("Migration ID 不能为空");
+    if (!migration.checksum.trim()) {
+      throw new Error(`Migration ${migration.id} 缺少 checksum`);
+    }
+  }
+}
+
+function validateMigrationDependencies(
+  bundle: MigrationBundle,
+  owners: ReadonlyMap<string, string>,
+): void {
+  for (const migration of bundle.migrations) {
+    for (const dependency of migration.dependsOn || []) {
+      const owner = owners.get(dependency);
+      if (!owner) {
+        throw new Error(`Migration ${migration.id} 依赖不存在：${dependency}`);
+      }
+      if (
+        owner !== bundle.module &&
+        !(bundle.dependencies || []).includes(owner)
+      ) {
+        throw new Error(
+          `Migration ${migration.id} 跨模块依赖 ${owner}，但 Bundle 未声明该模块依赖`,
+        );
+      }
+    }
+  }
+}
+
+function topologicalBundles(
+  pendingSource: ReadonlyMap<string, MigrationBundle>,
+): MigrationBundle[] {
+  const pending = new Map(pendingSource);
+  const sorted: MigrationBundle[] = [];
+  while (pending.size > 0) {
+    const ready = Array.from(pending.values()).find((bundle) =>
+      (bundle.dependencies || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) throw new Error("Migration Bundle 模块依赖存在循环");
+    sorted.push(ready);
+    pending.delete(ready.module);
+  }
+  return sorted;
+}
+
+export function orderBundleMigrations(
+  bundle: MigrationBundle,
+): BundleMigrationDefinition[] {
+  const pending = new Map(
+    bundle.migrations.map((migration) => [migration.id, migration]),
+  );
+  const sorted: BundleMigrationDefinition[] = [];
+  while (pending.size > 0) {
+    const ready = Array.from(pending.values()).find((migration) =>
+      (migration.dependsOn || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) {
+      throw new Error(`Migration Bundle ${bundle.module} 的迁移依赖存在循环`);
+    }
+    sorted.push(ready);
+    pending.delete(ready.id);
+  }
+  return sorted;
+}

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

@@ -5,7 +5,7 @@ import type {
   DialectCapabilities,
   PageRequest,
   PaginationSqlParts,
-} from "@windy/shared";
+} from "@southwind-ai/shared";
 
 const reservedWords: Record<DatabaseDialect, string[]> = {
   postgresql: ["user", "role", "order"],

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