create-windy 0.1.0

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

@@ -0,0 +1,343 @@
+import { describe, expect, test } from "bun:test";
+import { getTableConfig } from "drizzle-orm/pg-core";
+import { featureFlags } from "./schema/index.js";
+// @windy-module system.bulk-data begin
+import { bulkDataArtifacts, bulkDataJobs } from "./schema/index.js";
+// @windy-module system.bulk-data end
+// @windy-module system.scheduler begin
+import {
+  durableJobArtifacts,
+  durableJobAttempts,
+  durableJobFailures,
+  durableJobLeases,
+  durableJobProgress,
+  durableJobRecoveries,
+  durableJobStages,
+  durableJobs,
+  scheduledTaskRuns,
+  scheduledTasks,
+} from "./schema/index.js";
+// @windy-module system.scheduler end
+// @windy-module system.storage begin
+import {
+  fileMetadata,
+  fileUploadParts,
+  fileUploadSessions,
+} from "./schema/index.js";
+// @windy-module system.storage end
+// @windy-module system.license begin
+import {
+  legacyLicenseIssueRecords,
+  legacyLicenseProjects,
+  legacyLicenses,
+  licenseContractVersions,
+  licenseCustomers,
+  licenseEvents,
+  licenseGovernanceEvents,
+  licenseKeyCompatibilities,
+  licenseKeys,
+  licenseNodes,
+  licenseOperatorSessions,
+  licenseOperators,
+  licenseProjects,
+  licenseReplacements,
+  licenseVersions,
+  licenses,
+} from "./schema/index.js";
+// @windy-module system.license end
+
+describe("database schema", () => {
+  test("feature_flags 保持完整审计和软删除字段", () => {
+    expect("createdAt" in featureFlags).toBe(true);
+    expect("createdBy" in featureFlags).toBe(true);
+    expect("updatedAt" in featureFlags).toBe(true);
+    expect("updatedBy" in featureFlags).toBe(true);
+    expect("deletedAt" in featureFlags).toBe(true);
+    expect("deletedBy" in featureFlags).toBe(true);
+  });
+
+  // @windy-module system.license begin
+  test("V1 License 关系具有必填引用、到期时间和归档字段", () => {
+    expect(licenses.formatVersion.notNull).toBe(true);
+    expect(licenses.productCode.notNull).toBe(true);
+    expect(licenses.customerId.notNull).toBe(true);
+    expect(licenses.projectId.notNull).toBe(true);
+    expect(licenses.contractVersionId.notNull).toBe(true);
+    expect(licenses.nodeId.notNull).toBe(true);
+    expect(licenses.expiresAt.notNull).toBe(true);
+    expect(licenses.licenseVersionKey).toBeDefined();
+    expect(licenseContractVersions.licenseVersionId.notNull).toBe(true);
+    expect(licenseVersions.projectId.notNull).toBe(true);
+    expect("modules" in licenses).toBe(false);
+    expect("limits" in licenses).toBe(false);
+    expect("notBefore" in licenses).toBe(false);
+
+    for (const table of [
+      licenseCustomers,
+      licenseProjects,
+      licenseContractVersions,
+      licenseVersions,
+      licenseNodes,
+    ]) {
+      expect("archivedAt" in table).toBe(true);
+      expect("archivedBy" in table).toBe(true);
+      expect("deletedAt" in table).toBe(false);
+    }
+  });
+
+  test("客户、项目、合同、节点和历史关系禁止级联删除", () => {
+    const relatedTables = [
+      licenseProjects,
+      licenseContractVersions,
+      licenseNodes,
+      licenses,
+      licenseReplacements,
+      licenseEvents,
+    ];
+    const foreignKeys = relatedTables.flatMap(
+      (table) => getTableConfig(table).foreignKeys,
+    );
+
+    expect(foreignKeys.length).toBeGreaterThanOrEqual(9);
+    expect(
+      foreignKeys.every((foreignKey) => foreignKey.onDelete === "restrict"),
+    ).toBe(true);
+  });
+
+  test("旧原型表具有独立 legacy 表名", () => {
+    expect(getTableConfig(legacyLicenseProjects).name).toBe(
+      "legacy_license_projects",
+    );
+    expect(getTableConfig(legacyLicenseIssueRecords).name).toBe(
+      "legacy_license_issue_records",
+    );
+    expect(getTableConfig(legacyLicenses).name).toBe("legacy_licenses");
+  });
+
+  test("签发中心操作员使用独立密码和会话表", async () => {
+    expect(getTableConfig(licenseOperators).name).toBe("license_operators");
+    expect(licenseOperators.passwordHash.dataType).toBe("string");
+    expect(licenseOperators.role.notNull).toBe(true);
+    expect(getTableConfig(licenseOperatorSessions).name).toBe(
+      "license_operator_sessions",
+    );
+    expect(licenseOperatorSessions.tokenHash.notNull).toBe(true);
+    expect(licenseOperatorSessions.expiresAt.notNull).toBe(true);
+    expect(
+      getTableConfig(licenseOperatorSessions).foreignKeys[0]?.onDelete,
+    ).toBe("restrict");
+
+    const migration = await Bun.file(
+      new URL("../drizzle/0008_secret_toxin.sql", import.meta.url),
+    ).text();
+    expect(migration).toContain('CREATE TABLE "license_operator_sessions"');
+    expect(migration).toContain(
+      'ALTER TABLE "license_operators" ADD COLUMN "password_hash" text',
+    );
+    expect(migration).not.toContain('REFERENCES "public"."users"');
+    expect(migration).not.toContain('REFERENCES "public"."server_sessions"');
+  });
+
+  test("V1 migration 通过表重命名保留旧原型数据", async () => {
+    const migration = await Bun.file(
+      new URL("../drizzle/0006_groovy_overlord.sql", import.meta.url),
+    ).text();
+
+    expect(migration).toContain(
+      'ALTER TABLE "license_issue_records" RENAME TO "legacy_license_issue_records"',
+    );
+    expect(migration).toContain(
+      'ALTER TABLE "license_projects" RENAME TO "legacy_license_projects"',
+    );
+    expect(migration).toContain(
+      'ALTER TABLE "licenses" RENAME TO "legacy_licenses"',
+    );
+    expect(migration).not.toContain('DROP TABLE "legacy_');
+    expect(migration).not.toContain('DROP TABLE "license_');
+  });
+
+  test("LIC-06 schema 保存公钥兼容声明并由 migration 强制不可变", async () => {
+    expect(licenses.targetSoftwareVersion.dataType).toBe("string");
+    expect(licenseKeys.retainUntil.dataType).toBe("date");
+    expect(getTableConfig(licenseKeyCompatibilities).name).toBe(
+      "license_key_compatibilities",
+    );
+    expect(getTableConfig(licenseGovernanceEvents).name).toBe(
+      "license_governance_events",
+    );
+    expect(
+      getTableConfig(licenseKeyCompatibilities).foreignKeys[0]?.onDelete,
+    ).toBe("restrict");
+
+    const migration = await Bun.file(
+      new URL("../drizzle/0009_ambiguous_adam_warlock.sql", import.meta.url),
+    ).text();
+    for (const trigger of [
+      "trg_licenses_immutable",
+      "trg_license_events_append_only",
+      "trg_license_replacements_append_only",
+      "trg_license_governance_events_append_only",
+      "trg_license_key_compatibilities_append_only",
+      "trg_license_keys_no_delete",
+    ]) {
+      expect(migration).toContain(`CREATE TRIGGER "${trigger}"`);
+    }
+    expect(migration).not.toContain("ON DELETE cascade");
+  });
+  // @windy-module system.license end
+
+  // @windy-module system.scheduler begin
+  test("定时任务定义与执行历史具备持久化并发约束", () => {
+    expect(getTableConfig(scheduledTasks).name).toBe("scheduled_tasks");
+    expect(scheduledTasks.nextRunAt.notNull).toBe(true);
+    expect(scheduledTasks.intervalSeconds.notNull).toBe(true);
+    expect(getTableConfig(scheduledTaskRuns).name).toBe("scheduled_task_runs");
+    expect(scheduledTaskRuns.taskKey.notNull).toBe(true);
+    expect(scheduledTaskRuns.attempt.notNull).toBe(true);
+    expect(getTableConfig(scheduledTaskRuns).foreignKeys[0]?.onDelete).toBe(
+      "restrict",
+    );
+    expect(
+      getTableConfig(scheduledTaskRuns).indexes.some(
+        (index) =>
+          index.config.name === "uk_scheduled_task_runs_single_running" &&
+          index.config.unique &&
+          Boolean(index.config.where),
+      ),
+    ).toBe(true);
+  });
+  // @windy-module system.scheduler end
+
+  // @windy-module system.bulk-data begin
+  test("批量任务幂等、进度和 artifact 留存由 PostgreSQL 约束", async () => {
+    expect(getTableConfig(bulkDataJobs).name).toBe("bulk_data_jobs");
+    expect(bulkDataJobs.idempotencyKey.notNull).toBe(true);
+    expect(bulkDataJobs.processedRows.notNull).toBe(true);
+    expect(
+      getTableConfig(bulkDataJobs).indexes.some(
+        (index) =>
+          index.config.name === "uk_bulk_data_jobs_idempotency" &&
+          index.config.unique,
+      ),
+    ).toBe(true);
+    expect(getTableConfig(bulkDataArtifacts).name).toBe("bulk_data_artifacts");
+    expect(bulkDataArtifacts.content.notNull).toBe(false);
+    expect(bulkDataArtifacts.artifactRef.notNull).toBe(false);
+    expect(bulkDataArtifacts.expiresAt.notNull).toBe(true);
+    expect(getTableConfig(bulkDataArtifacts).foreignKeys[0]?.onDelete).toBe(
+      "restrict",
+    );
+    const migration = await Bun.file(
+      new URL("../drizzle/0011_lowly_maria_hill.sql", import.meta.url),
+    ).text();
+    expect(migration).toContain('CREATE TABLE "bulk_data_jobs"');
+    expect(migration).toContain('CREATE TABLE "bulk_data_artifacts"');
+  });
+  // @windy-module system.bulk-data end
+
+  // @windy-module system.storage begin
+  test("文件上传会话、分片和文件元数据具有续传与清理索引", async () => {
+    expect(getTableConfig(fileUploadSessions).name).toBe(
+      "file_upload_sessions",
+    );
+    expect(fileUploadSessions.receivedByteSize.notNull).toBe(true);
+    expect(fileUploadSessions.nextPartNumber.notNull).toBe(true);
+    expect(getTableConfig(fileUploadParts).indexes).toHaveLength(2);
+    expect(getTableConfig(fileUploadParts).foreignKeys[0]?.onDelete).toBe(
+      "cascade",
+    );
+    expect(getTableConfig(fileMetadata).name).toBe("file_metadata");
+    expect(fileMetadata.artifactRef.notNull).toBe(true);
+    const migration = await Bun.file(
+      new URL("../drizzle/0021_plain_paladin.sql", import.meta.url),
+    ).text();
+    expect(migration).toContain('CREATE TABLE "file_upload_sessions"');
+    expect(migration).toContain(
+      'CREATE UNIQUE INDEX "uk_file_metadata_artifact_ref"',
+    );
+  });
+  // @windy-module system.storage end
+
+  // @windy-module system.scheduler begin
+  test("durable job 七类事实具备幂等、租约和不可变历史约束", async () => {
+    expect(getTableConfig(durableJobs).name).toBe("durable_jobs");
+    expect(durableJobs.payload.notNull).toBe(true);
+    expect(
+      getTableConfig(durableJobs).indexes.some(
+        (index) =>
+          index.config.name === "uk_durable_jobs_idempotency" &&
+          index.config.unique,
+      ),
+    ).toBe(true);
+    expect(getTableConfig(durableJobStages).name).toBe("durable_job_stages");
+    expect(getTableConfig(durableJobAttempts).name).toBe(
+      "durable_job_attempts",
+    );
+    expect(getTableConfig(durableJobLeases).name).toBe("durable_job_leases");
+    expect(
+      getTableConfig(durableJobLeases).indexes.some(
+        (index) =>
+          index.config.name === "uk_durable_job_leases_active_stage" &&
+          index.config.unique &&
+          Boolean(index.config.where),
+      ),
+    ).toBe(true);
+    expect(getTableConfig(durableJobProgress).name).toBe(
+      "durable_job_progress",
+    );
+    expect(getTableConfig(durableJobArtifacts).name).toBe(
+      "durable_job_artifacts",
+    );
+    expect(durableJobArtifacts.artifactRef.notNull).toBe(true);
+    expect(getTableConfig(durableJobFailures).name).toBe(
+      "durable_job_failures",
+    );
+    for (const table of [
+      durableJobStages,
+      durableJobAttempts,
+      durableJobLeases,
+      durableJobProgress,
+      durableJobArtifacts,
+      durableJobFailures,
+    ]) {
+      expect(
+        getTableConfig(table).foreignKeys.every(
+          (foreignKey) => foreignKey.onDelete === "restrict",
+        ),
+      ).toBe(true);
+    }
+    const migration = await Bun.file(
+      new URL("../drizzle/0023_fresh_thunderbolt_ross.sql", import.meta.url),
+    ).text();
+    expect(migration).toContain('CREATE TABLE "durable_jobs"');
+    expect(migration).toContain('CREATE TABLE "durable_job_leases"');
+    expect(migration).toContain(
+      'CREATE UNIQUE INDEX "uk_durable_job_leases_active_stage"',
+    );
+  });
+
+  test("durable job 人工恢复事实按任务与外部请求幂等", async () => {
+    expect(getTableConfig(durableJobRecoveries).name).toBe(
+      "durable_job_recoveries",
+    );
+    expect(durableJobRecoveries.reason.notNull).toBe(true);
+    expect(getTableConfig(durableJobRecoveries).foreignKeys[0]?.onDelete).toBe(
+      "restrict",
+    );
+    expect(
+      getTableConfig(durableJobRecoveries).indexes.some(
+        (index) =>
+          index.config.name === "uk_durable_job_recoveries_idempotency" &&
+          index.config.unique,
+      ),
+    ).toBe(true);
+    const migration = await Bun.file(
+      new URL("../drizzle/0024_misty_lizard.sql", import.meta.url),
+    ).text();
+    expect(migration).toContain('CREATE TABLE "durable_job_recoveries"');
+    expect(migration).toContain(
+      'CREATE UNIQUE INDEX "uk_durable_job_recoveries_idempotency"',
+    );
+  });
+  // @windy-module system.scheduler end
+});

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

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createPostgresStatementExecutor,
+  PostgresMigrationHistoryStore,
+  splitDrizzleSqlStatements,
+  type QueryableClient,
+} from "./sql-store.js";
+
+class QueryRecorder implements QueryableClient {
+  calls: Array<{ sql: string; params?: unknown[] }> = [];
+
+  constructor(private readonly rows: Record<string, unknown>[] = []) {}
+
+  async query<Row = Record<string, unknown>>(sql: string, params?: unknown[]) {
+    this.calls.push({ sql, params });
+    return { rows: this.rows as Row[] };
+  }
+}
+
+describe("PostgresMigrationHistoryStore", () => {
+  test("读取已执行迁移并映射为统一历史记录", async () => {
+    const store = new PostgresMigrationHistoryStore(
+      new QueryRecorder([
+        {
+          id: "system.001",
+          module: "system",
+          direction: "up",
+          status: "applied",
+          checksum: null,
+          statements: ["create table users (id varchar(64))"],
+          error: null,
+          started_at: new Date("2026-07-09T00:00:00.000Z"),
+          finished_at: "2026-07-09T00:00:01.000Z",
+        },
+      ]),
+    );
+
+    await expect(store.listApplied()).resolves.toEqual([
+      {
+        id: "system.001",
+        module: "system",
+        direction: "up",
+        status: "applied",
+        startedAt: "2026-07-09T00:00:00.000Z",
+        finishedAt: "2026-07-09T00:00:01.000Z",
+        statements: ["create table users (id varchar(64))"],
+      },
+    ]);
+  });
+
+  test("记录迁移历史时写入 upsert SQL 和 statement JSON", async () => {
+    const client = new QueryRecorder();
+    const store = new PostgresMigrationHistoryStore(client);
+
+    await store.record({
+      id: "system.001",
+      module: "system",
+      direction: "up",
+      status: "applied",
+      startedAt: "2026-07-09T00:00:00.000Z",
+      finishedAt: "2026-07-09T00:00:01.000Z",
+      statements: ["create table users (id varchar(64))"],
+    });
+
+    expect(client.calls[0]?.sql).toContain("on conflict (id) do update");
+    expect(client.calls[0]?.params?.[5]).toBe(
+      JSON.stringify(["create table users (id varchar(64))"]),
+    );
+  });
+});
+
+describe("SQL migration helpers", () => {
+  test("拆分 Drizzle statement breakpoint 并通过执行器发给 client", async () => {
+    const statements = splitDrizzleSqlStatements(
+      "create table a (id varchar(64));--> statement-breakpoint\ncreate index idx_a on a(id);",
+    );
+    const client = new QueryRecorder();
+    const execute = createPostgresStatementExecutor(client);
+
+    for (const statement of statements) {
+      await execute(statement);
+    }
+
+    expect(statements).toEqual([
+      { sql: "create table a (id varchar(64));" },
+      { sql: "create index idx_a on a(id);" },
+    ]);
+    expect(client.calls.map((call) => call.sql)).toEqual(
+      statements.map((statement) => statement.sql),
+    );
+  });
+});

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

@@ -0,0 +1,101 @@
+import type { MigrationStatement } from "@windy/shared";
+import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
+
+export interface QueryResult<Row> {
+  rows: Row[];
+}
+
+export interface QueryableClient {
+  query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<QueryResult<Row>>;
+}
+
+interface MigrationHistoryRow {
+  id: string;
+  module: string;
+  direction: "up" | "down";
+  status: "applied" | "failed";
+  checksum: string | null;
+  statements: string[] | null;
+  error: string | null;
+  started_at: Date | string;
+  finished_at: Date | string;
+}
+
+export class PostgresMigrationHistoryStore implements MigrationHistoryStore {
+  constructor(private readonly client: QueryableClient) {}
+
+  async listApplied(): Promise<MigrationHistoryEntry[]> {
+    const result = await this.client.query<MigrationHistoryRow>(
+      `select id, module, direction, status, checksum, statements, error, started_at, finished_at
+       from windy_migration_history
+       where status = $1
+       order by finished_at asc`,
+      ["applied"],
+    );
+
+    return result.rows.map(mapHistoryRow);
+  }
+
+  async record(entry: MigrationHistoryEntry): Promise<void> {
+    await this.client.query(
+      `insert into windy_migration_history
+         (id, module, direction, status, checksum, statements, error, started_at, finished_at)
+       values ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9)
+       on conflict (id) do update set
+         module = excluded.module,
+         direction = excluded.direction,
+         status = excluded.status,
+         checksum = excluded.checksum,
+         statements = excluded.statements,
+         error = excluded.error,
+         started_at = excluded.started_at,
+         finished_at = excluded.finished_at`,
+      [
+        entry.id,
+        entry.module,
+        entry.direction,
+        entry.status,
+        entry.checksum || null,
+        JSON.stringify(entry.statements || []),
+        entry.error || null,
+        entry.startedAt,
+        entry.finishedAt,
+      ],
+    );
+  }
+}
+
+export function createPostgresStatementExecutor(client: QueryableClient) {
+  return async (statement: MigrationStatement): Promise<void> => {
+    await client.query(statement.sql, statement.params);
+  };
+}
+
+export function splitDrizzleSqlStatements(sql: string): MigrationStatement[] {
+  return sql
+    .split("--> statement-breakpoint")
+    .map((statement) => statement.trim())
+    .filter(Boolean)
+    .map((statement) => ({ sql: statement }));
+}
+
+function mapHistoryRow(row: MigrationHistoryRow): MigrationHistoryEntry {
+  return {
+    id: row.id,
+    module: row.module,
+    direction: row.direction,
+    status: row.status,
+    startedAt: toIsoString(row.started_at),
+    finishedAt: toIsoString(row.finished_at),
+    checksum: row.checksum || undefined,
+    statements: row.statements || undefined,
+    error: row.error || undefined,
+  };
+}
+
+function toIsoString(value: Date | string): string {
+  return value instanceof Date ? value.toISOString() : value;
+}

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

@@ -0,0 +1,32 @@
+import type { ISODateTime } from "@windy/shared";
+
+export type MigrationStatus = "applied" | "failed";
+
+export interface MigrationHistoryEntry {
+  id: string;
+  module: string;
+  direction: "up" | "down";
+  status: MigrationStatus;
+  startedAt: ISODateTime;
+  finishedAt: ISODateTime;
+  checksum?: string;
+  statements?: string[];
+  error?: string;
+}
+
+export interface MigrationHistoryStore {
+  listApplied(): Promise<MigrationHistoryEntry[]>;
+  record(entry: MigrationHistoryEntry): Promise<void>;
+}
+
+export class InMemoryMigrationHistoryStore implements MigrationHistoryStore {
+  private readonly entries: MigrationHistoryEntry[] = [];
+
+  async listApplied(): Promise<MigrationHistoryEntry[]> {
+    return this.entries.filter((entry) => entry.status === "applied");
+  }
+
+  async record(entry: MigrationHistoryEntry): Promise<void> {
+    this.entries.push(entry);
+  }
+}

package/template/packages/database/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext", "dom"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*", "index.ts"],
+  "exclude": ["node_modules", "dist"]
+}

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

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

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

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

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

@@ -0,0 +1,50 @@
+import type {
+  EntityAuditFields,
+  LifecycleStatus,
+  PageResult,
+} from "@windy/shared";
+
+export const workOrderPriorities = ["low", "medium", "high"] as const;
+export const workOrderWorkflowStatuses = [
+  "open",
+  "in-progress",
+  "resolved",
+] as const;
+
+export type WorkOrderPriority = (typeof workOrderPriorities)[number];
+export type WorkOrderWorkflowStatus =
+  (typeof workOrderWorkflowStatuses)[number];
+
+export interface WorkOrder extends EntityAuditFields {
+  id: string;
+  title: string;
+  description: string;
+  priority: WorkOrderPriority;
+  workflowStatus: WorkOrderWorkflowStatus;
+  ownerId: string;
+  departmentId?: string;
+  status: LifecycleStatus;
+}
+
+export interface CreateWorkOrderInput {
+  title: string;
+  description: string;
+  priority: WorkOrderPriority;
+}
+
+export interface UpdateWorkOrderInput {
+  title?: string;
+  description?: string;
+  priority?: WorkOrderPriority;
+  workflowStatus?: WorkOrderWorkflowStatus;
+  ownerId?: string;
+  departmentId?: string;
+}
+
+export interface WorkOrderListQuery {
+  page?: number;
+  pageSize?: number;
+  q?: string;
+}
+
+export type WorkOrderPage = PageResult<WorkOrder>;