create-windy 0.1.0

package/template/packages/config/src/secrets.ts

@@ -0,0 +1,69 @@
+export type SecretProviderKey = "env" | "file";
+
+export class SecretRef {
+  readonly #provider: SecretProviderKey;
+  readonly #locator: string;
+
+  constructor(provider: SecretProviderKey, locator: string) {
+    this.#provider = provider;
+    this.#locator = locator;
+    Object.freeze(this);
+  }
+
+  locatorFor(provider: SecretProviderKey): string {
+    if (provider !== this.#provider) {
+      throw new Error("SecretResolver 与 SecretRef Provider 不匹配");
+    }
+    return this.#locator;
+  }
+
+  toJSON(): undefined {
+    return undefined;
+  }
+
+  toString(): string {
+    return "[SecretRef]";
+  }
+}
+
+export interface SecretResolver {
+  resolve(ref: SecretRef): string | undefined | Promise<string | undefined>;
+}
+
+export class EnvironmentSecretResolver implements SecretResolver {
+  constructor(
+    private readonly environment: Readonly<Record<string, string | undefined>>,
+  ) {}
+
+  resolve(ref: SecretRef): string | undefined {
+    return this.environment[ref.locatorFor("env")];
+  }
+}
+
+export class CompositeSecretResolver implements SecretResolver {
+  constructor(
+    private readonly resolvers: Readonly<
+      Partial<Record<SecretProviderKey, SecretResolver>>
+    >,
+  ) {}
+
+  resolve(ref: SecretRef): string | undefined | Promise<string | undefined> {
+    for (const provider of ["env", "file"] as const) {
+      try {
+        ref.locatorFor(provider);
+        const resolver = this.resolvers[provider];
+        if (!resolver) throw new Error("Secret Provider 未配置");
+        return resolver.resolve(ref);
+      } catch (error) {
+        if (
+          error instanceof Error &&
+          error.message === "SecretResolver 与 SecretRef Provider 不匹配"
+        ) {
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error("未知 Secret Provider");
+  }
+}

package/template/packages/crud-generator/index.ts

@@ -0,0 +1,3 @@
+export * from "./src/definition.js";
+export * from "./src/generator.js";
+export * from "./src/validation.js";

package/template/packages/crud-generator/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@windy/crud-generator",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/template/packages/crud-generator/src/cli.ts

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { generateCrudModule } from "./generator.js";
+
+const options = readOptions(process.argv.slice(2));
+const raw = JSON.parse(await readFile(options.spec, "utf8")) as unknown;
+const result = await generateCrudModule(raw, {
+  outputDirectory: options.output,
+});
+process.stdout.write(
+  `已生成 CRUD 模块：${result.outputDirectory}\n${result.files.join("\n")}\n`,
+);
+
+function readOptions(args: string[]): { spec: string; output: string } {
+  const values = new Map<string, string>();
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index];
+    const value = args[index + 1];
+    if (!key?.startsWith("--") || !value) usage();
+    values.set(key.slice(2), value);
+  }
+  const spec = values.get("spec");
+  const output = values.get("output");
+  if (!spec || !output || values.size !== 2) usage();
+  return { spec, output };
+}
+
+function usage(): never {
+  throw new Error(
+    "用法：bun run generate:crud -- --spec <metadata.json> --output <target-directory>",
+  );
+}

package/template/packages/crud-generator/src/definition.ts

@@ -0,0 +1,48 @@
+export type CrudFieldType =
+  | "string"
+  | "integer"
+  | "boolean"
+  | "datetime"
+  | "json";
+
+export interface CrudFieldDefinition {
+  name: string;
+  column: string;
+  label: string;
+  type: CrudFieldType;
+  required?: boolean;
+  unique?: boolean;
+  searchable?: boolean;
+  maxLength?: number;
+}
+
+export interface CrudModuleDefinition {
+  schemaVersion: 1;
+  module: {
+    name: string;
+    label: string;
+    description: string;
+    version: string;
+  };
+  entity: {
+    name: string;
+    pluralName: string;
+    label: string;
+    table: string;
+    resource: string;
+    route: string;
+    featureKey: string;
+    featureLabel: string;
+    allowedLicenseVersions?: string[];
+    fields: CrudFieldDefinition[];
+  };
+}
+
+export interface GenerateCrudOptions {
+  outputDirectory: string;
+}
+
+export interface GeneratedCrudResult {
+  outputDirectory: string;
+  files: string[];
+}

package/template/packages/crud-generator/src/generator.test.ts

@@ -0,0 +1,180 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { generateCrudModule } from "./generator.js";
+import { parseCrudModuleDefinition } from "./validation.js";
+
+const workspaceRoot = resolve(import.meta.dir, "../../..");
+const fixtureRoot = resolve(workspaceRoot, ".tmp/crud-generator");
+const output = resolve(fixtureRoot, "inventory-item");
+const fixture = {
+  schemaVersion: 1,
+  module: {
+    name: "inventory",
+    label: "库存管理",
+    description: "库存物料独立模块。",
+    version: "0.1.0",
+  },
+  entity: {
+    name: "InventoryItem",
+    pluralName: "InventoryItems",
+    label: "库存物料",
+    table: "inventory_items",
+    resource: "item",
+    route: "/api/inventory/items",
+    featureKey: "inventory.item",
+    featureLabel: "库存物料管理",
+    allowedLicenseVersions: ["standard", "advanced"],
+    fields: [
+      {
+        name: "code",
+        column: "code",
+        label: "物料编码",
+        type: "string",
+        maxLength: 80,
+        required: true,
+        unique: true,
+        searchable: true,
+      },
+      {
+        name: "name",
+        column: "name",
+        label: "物料名称",
+        type: "string",
+        maxLength: 120,
+        required: true,
+        searchable: true,
+      },
+      {
+        name: "quantity",
+        column: "quantity",
+        label: "库存数量",
+        type: "integer",
+        required: true,
+      },
+      {
+        name: "available",
+        column: "available",
+        label: "是否可用",
+        type: "boolean",
+        required: true,
+      },
+      {
+        name: "checkedAt",
+        column: "checked_at",
+        label: "盘点时间",
+        type: "datetime",
+      },
+      {
+        name: "attributes",
+        column: "attributes",
+        label: "扩展属性",
+        type: "json",
+      },
+    ],
+  },
+};
+
+afterAll(async () => {
+  await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+describe("CRUD generator", () => {
+  test("生成 fixture 可通过 typecheck 和测试且文件小于 350 行", async () => {
+    await rm(fixtureRoot, { recursive: true, force: true });
+    await mkdir(fixtureRoot, { recursive: true });
+    const result = await generateCrudModule(fixture, {
+      outputDirectory: output,
+    });
+    await symlink(
+      resolve(workspaceRoot, "apps/server/node_modules"),
+      resolve(output, "node_modules"),
+      "dir",
+    );
+    const fixtureTsconfig = resolve(output, "tsconfig.fixture.json");
+    await writeFile(
+      fixtureTsconfig,
+      JSON.stringify({
+        extends: "./tsconfig.json",
+        compilerOptions: {
+          typeRoots: [resolve(workspaceRoot, "node_modules/@types")],
+        },
+      }),
+    );
+    expect(result.files).toContain("src/drizzle-repository.ts");
+    expect(result.files).toContain("src/manifest.ts");
+    const manifestSource = await readFile(
+      resolve(output, "src/manifest.ts"),
+      "utf8",
+    );
+    expect(manifestSource).toContain("menus: []");
+    expect(manifestSource).toContain("adminRoutes: []");
+    for (const file of result.files.filter((path) => path.endsWith(".ts"))) {
+      const source = await readFile(resolve(output, file), "utf8");
+      expect(source.split("\n").length).toBeLessThanOrEqual(350);
+    }
+
+    const typecheck = Bun.spawnSync(
+      ["bun", "x", "tsc", "--noEmit", "--project", fixtureTsconfig],
+      { cwd: workspaceRoot, stdout: "pipe", stderr: "pipe" },
+    );
+    expect(
+      typecheck.exitCode,
+      `${typecheck.stdout.toString()}\n${typecheck.stderr.toString()}`,
+    ).toBe(0);
+    const tests = Bun.spawnSync(["bun", "test", resolve(output, "src")], {
+      cwd: workspaceRoot,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    expect(
+      tests.exitCode,
+      `${tests.stdout.toString()}\n${tests.stderr.toString()}`,
+    ).toBe(0);
+  }, 30_000);
+
+  test("目标已存在时拒绝覆盖且保持原文件", async () => {
+    const marker = resolve(output, "marker.txt");
+    await Bun.write(marker, "owned-by-user");
+    await expect(
+      generateCrudModule(fixture, { outputDirectory: output }),
+    ).rejects.toThrow("拒绝覆盖");
+    expect(await readFile(marker, "utf8")).toBe("owned-by-user");
+  });
+
+  test("拒绝保留字段和非字符串搜索字段", () => {
+    const invalid = structuredClone(fixture);
+    invalid.entity.fields[0]!.name = "id";
+    invalid.entity.fields[2]!.searchable = true;
+    expect(() => parseCrudModuleDefinition(invalid)).toThrow("保留字段");
+  });
+
+  test("拒绝重复的 License 版本", () => {
+    const invalid = structuredClone(fixture);
+    invalid.entity.allowedLicenseVersions = ["advanced", "advanced"];
+    expect(() => parseCrudModuleDefinition(invalid)).toThrow(
+      "License 版本不能重复",
+    );
+  });
+
+  test("未知 canonical 字段和路径逃逸在创建临时目录前 fail-fast", async () => {
+    const unknown = structuredClone(fixture) as typeof fixture & {
+      compatibility?: string;
+    };
+    unknown.compatibility = "legacy";
+    expect(() => parseCrudModuleDefinition(unknown)).toThrow("未知字段");
+
+    const escaping = structuredClone(fixture);
+    escaping.entity.route = "/api/inventory/../secrets";
+    await expect(
+      generateCrudModule(escaping, {
+        outputDirectory: resolve(fixtureRoot, "must-not-exist"),
+      }),
+    ).rejects.toThrow("entity.route 格式无效");
+    expect(
+      await Bun.file(
+        resolve(fixtureRoot, "must-not-exist/package.json"),
+      ).exists(),
+    ).toBe(false);
+  });
+});

package/template/packages/crud-generator/src/generator.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import type { GenerateCrudOptions, GeneratedCrudResult } from "./definition.js";
+import {
+  domainTemplate,
+  drizzleRepositoryTemplate,
+  dtoTemplate,
+  manifestTemplate,
+  repositoryTemplate,
+  routesTemplate,
+  schemaTemplate,
+  serviceTemplate,
+} from "./templates/index.js";
+import {
+  barrelTemplate,
+  packageTemplate,
+  routeTestTemplate,
+  serviceTestTemplate,
+  tsconfigTemplate,
+} from "./templates/project.js";
+import { parseCrudModuleDefinition } from "./validation.js";
+
+type OutputFiles = Record<string, string>;
+
+export async function generateCrudModule(
+  rawDefinition: unknown,
+  options: GenerateCrudOptions,
+): Promise<GeneratedCrudResult> {
+  const definition = parseCrudModuleDefinition(rawDefinition);
+  const outputDirectory = resolve(options.outputDirectory);
+  await assertTargetAbsent(outputDirectory);
+  const staging = `${outputDirectory}.tmp-${randomUUID()}`;
+  const files = renderFiles(definition);
+
+  try {
+    await mkdir(resolve(staging, "src"), { recursive: true });
+    for (const [relativePath, contents] of Object.entries(files)) {
+      const target = resolve(staging, relativePath);
+      assertInside(staging, target);
+      await writeFile(target, contents, { encoding: "utf8", flag: "wx" });
+    }
+    await mkdir(dirname(outputDirectory), { recursive: true });
+    await rename(staging, outputDirectory);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+
+  return {
+    outputDirectory,
+    files: Object.keys(files).sort(),
+  };
+}
+
+function renderFiles(
+  definition: ReturnType<typeof parseCrudModuleDefinition>,
+): OutputFiles {
+  return {
+    "package.json": packageTemplate(definition),
+    "tsconfig.json": tsconfigTemplate(),
+    "src/domain.ts": domainTemplate(definition),
+    "src/dto.ts": dtoTemplate(definition),
+    "src/schema.ts": schemaTemplate(definition),
+    "src/repository.ts": repositoryTemplate(definition),
+    "src/drizzle-repository.ts": drizzleRepositoryTemplate(definition),
+    "src/service.ts": serviceTemplate(definition),
+    "src/routes.ts": routesTemplate(definition),
+    "src/manifest.ts": manifestTemplate(definition),
+    "src/index.ts": barrelTemplate(),
+    "src/service.test.ts": serviceTestTemplate(definition),
+    "src/routes.test.ts": routeTestTemplate(definition),
+  };
+}
+
+async function assertTargetAbsent(path: string): Promise<void> {
+  try {
+    await stat(path);
+    throw new Error(`拒绝覆盖已存在的生成目标：${path}`);
+  } catch (error) {
+    if (isMissing(error)) return;
+    throw error;
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+function assertInside(root: string, target: string): void {
+  const prefix = `${resolve(root)}/`;
+  if (!resolve(target).startsWith(prefix)) {
+    throw new Error(`生成文件越过目标目录：${target}`);
+  }
+}

package/template/packages/crud-generator/src/template-helpers.ts

@@ -0,0 +1,72 @@
+import type {
+  CrudFieldDefinition,
+  CrudModuleDefinition,
+} from "./definition.js";
+
+export function camel(value: string): string {
+  return value[0]!.toLowerCase() + value.slice(1);
+}
+
+export function kebab(value: string): string {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_\s]+/g, "-")
+    .toLowerCase();
+}
+
+export function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function domainType(field: CrudFieldDefinition): string {
+  if (field.type === "integer") return "number";
+  if (field.type === "boolean") return "boolean";
+  if (field.type === "json") return "Record<string, unknown>";
+  return "string";
+}
+
+export function zodType(field: CrudFieldDefinition): string {
+  let expression: string;
+  if (field.type === "string") {
+    expression = `z.string().trim().min(1).max(${field.maxLength})`;
+  } else if (field.type === "integer") {
+    expression = "z.number().int()";
+  } else if (field.type === "boolean") {
+    expression = "z.boolean()";
+  } else if (field.type === "datetime") {
+    expression = "z.string().datetime({ offset: true })";
+  } else {
+    expression = "z.record(z.string(), z.unknown())";
+  }
+  return field.required ? expression : `${expression}.optional()`;
+}
+
+export function columnType(field: CrudFieldDefinition): string {
+  if (field.type === "string") {
+    return `varchar(${quote(field.column)}, { length: ${field.maxLength} })`;
+  }
+  if (field.type === "integer") return `integer(${quote(field.column)})`;
+  if (field.type === "boolean") return `boolean(${quote(field.column)})`;
+  if (field.type === "datetime") {
+    return `timestamp(${quote(field.column)}, { withTimezone: true })`;
+  }
+  return `jsonb(${quote(field.column)}).$type<Record<string, unknown>>()`;
+}
+
+export function fieldPermission(
+  definition: CrudModuleDefinition,
+  action: "read" | "create" | "update" | "delete",
+): string {
+  return `${definition.module.name}.${definition.entity.resource}.${action}`;
+}
+
+export function importsForColumns(definition: CrudModuleDefinition): string[] {
+  const names = new Set(["pgTable", "timestamp", "varchar"]);
+  for (const field of definition.entity.fields) {
+    if (field.type === "integer") names.add("integer");
+    if (field.type === "boolean") names.add("boolean");
+    if (field.type === "json") names.add("jsonb");
+    if (field.unique) names.add("uniqueIndex");
+  }
+  return [...names].sort();
+}

package/template/packages/crud-generator/src/templates/domain.ts

@@ -0,0 +1,27 @@
+import type { CrudModuleDefinition } from "../definition.js";
+import { domainType } from "../template-helpers.js";
+
+export function domainTemplate(definition: CrudModuleDefinition): string {
+  const { entity } = definition;
+  const fields = entity.fields
+    .map(
+      (field) =>
+        `  ${field.name}${field.required ? "" : "?"}: ${domainType(field)};`,
+    )
+    .join("\n");
+  return `import type { EntityAuditFields, LifecycleStatus } from "@windy/shared";
+
+export interface ${entity.name} extends EntityAuditFields {
+  id: string;
+  status: LifecycleStatus;
+${fields}
+}
+
+export type ${entity.name}CreateInput = Pick<
+  ${entity.name},
+${entity.fields.map((field) => `  | "${field.name}"`).join("\n")}
+>;
+
+export type ${entity.name}UpdateInput = Partial<${entity.name}CreateInput>;
+`;
+}

package/template/packages/crud-generator/src/templates/drizzle-repository.ts

@@ -0,0 +1,126 @@
+import type { CrudModuleDefinition } from "../definition.js";
+import { camel } from "../template-helpers.js";
+
+export function drizzleRepositoryTemplate(
+  definition: CrudModuleDefinition,
+): string {
+  const { entity } = definition;
+  const table = camel(entity.pluralName);
+  const repository = `${entity.name}Repository`;
+  const searchable = entity.fields.filter((field) => field.searchable);
+  const search = searchable.length
+    ? `query.q
+        ? or(${searchable.map((field) => `ilike(${table}.${field.name}, \`%\${query.q}%\`)`).join(", ")})
+        : undefined`
+    : "undefined";
+  const databaseFields = entity.fields
+    .map((field) => {
+      const value = `input.${field.name}`;
+      return `    ${field.name}: ${field.type === "datetime" ? `${value} ? new Date(${value}) : undefined` : value},`;
+    })
+    .join("\n");
+  const domainFields = entity.fields
+    .map((field) => {
+      const value =
+        field.type === "datetime"
+          ? `row.${field.name}?.toISOString()`
+          : field.required
+            ? `row.${field.name}`
+            : `row.${field.name} ?? undefined`;
+      return `    ${field.name}: ${value},`;
+    })
+    .join("\n");
+  return `import { randomUUIDv7 } from "bun";
+import { and, count, desc, eq, ilike, isNull, or } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ${entity.name}, ${entity.name}CreateInput, ${entity.name}UpdateInput } from "./domain.js";
+import type { ${repository}, ${entity.name}ListQuery } from "./repository.js";
+import { ${table} } from "./schema.js";
+
+export class Drizzle${repository} implements ${repository} {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async list(query: ${entity.name}ListQuery) {
+    const where = and(
+      query.includeDeleted ? undefined : isNull(${table}.deletedAt),
+      ${search},
+    );
+    const offset = (query.page - 1) * query.pageSize;
+    const [rows, totalRows] = await Promise.all([
+      this.db.select().from(${table}).where(where).orderBy(desc(${table}.updatedAt)).limit(query.pageSize).offset(offset),
+      this.db.select({ value: count() }).from(${table}).where(where),
+    ]);
+    return {
+      items: rows.map(toDomain),
+      total: totalRows[0]?.value || 0,
+      page: query.page,
+      pageSize: query.pageSize,
+    };
+  }
+
+  async get(id: string): Promise<${entity.name} | undefined> {
+    const rows = await this.db.select().from(${table}).where(
+      and(eq(${table}.id, id), isNull(${table}.deletedAt)),
+    ).limit(1);
+    return rows[0] ? toDomain(rows[0]) : undefined;
+  }
+
+  async create(input: ${entity.name}CreateInput, actorId: string): Promise<${entity.name}> {
+    const now = new Date();
+    const values = {
+      id: randomUUIDv7(),
+      ...toDatabaseValues(input),
+      status: "active",
+      createdAt: now,
+      createdBy: actorId,
+      updatedAt: now,
+      updatedBy: actorId,
+    } as typeof ${table}.$inferInsert;
+    const rows = await this.db.insert(${table}).values(values).returning();
+    if (!rows[0]) throw new Error("创建 ${entity.label} 后未返回记录");
+    return toDomain(rows[0]);
+  }
+
+  async update(id: string, input: ${entity.name}UpdateInput, actorId: string) {
+    const rows = await this.db.update(${table}).set({
+      ...toDatabaseValues(input),
+      updatedAt: new Date(),
+      updatedBy: actorId,
+    }).where(and(eq(${table}.id, id), isNull(${table}.deletedAt))).returning();
+    return rows[0] ? toDomain(rows[0]) : undefined;
+  }
+
+  async softDelete(id: string, actorId: string) {
+    const now = new Date();
+    const rows = await this.db.update(${table}).set({
+      status: "archived",
+      deletedAt: now,
+      deletedBy: actorId,
+      updatedAt: now,
+      updatedBy: actorId,
+    }).where(and(eq(${table}.id, id), isNull(${table}.deletedAt))).returning();
+    return rows[0] ? toDomain(rows[0]) : undefined;
+  }
+}
+
+function toDatabaseValues(input: Partial<${entity.name}CreateInput>): Partial<typeof ${table}.$inferInsert> {
+  return {
+${databaseFields}
+  };
+}
+
+function toDomain(row: typeof ${table}.$inferSelect): ${entity.name} {
+  return {
+    id: row.id,
+    status: row.status as ${entity.name}["status"],
+${domainFields}
+    createdAt: row.createdAt.toISOString(),
+    createdBy: row.createdBy,
+    updatedAt: row.updatedAt.toISOString(),
+    updatedBy: row.updatedBy,
+    deletedAt: row.deletedAt?.toISOString(),
+    deletedBy: row.deletedBy || undefined,
+  };
+}
+`;
+}

package/template/packages/crud-generator/src/templates/dto.ts

@@ -0,0 +1,19 @@
+import type { CrudModuleDefinition } from "../definition.js";
+import { zodType } from "../template-helpers.js";
+
+export function dtoTemplate(definition: CrudModuleDefinition): string {
+  const { entity } = definition;
+  return `import { z } from "zod";
+
+export const create${entity.name}Schema = z.object({
+${entity.fields.map((field) => `  ${field.name}: ${zodType(field)},`).join("\n")}
+}).strict();
+
+export const update${entity.name}Schema = create${entity.name}Schema
+  .partial()
+  .refine((value) => Object.keys(value).length > 0, "至少提供一个可更新字段");
+
+export type Create${entity.name}Dto = z.infer<typeof create${entity.name}Schema>;
+export type Update${entity.name}Dto = z.infer<typeof update${entity.name}Schema>;
+`;
+}