create-windy 0.1.0

package/template/packages/modules/src/composition.test.ts

@@ -0,0 +1,267 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@windy/shared";
+import type { ModuleManifest } from "./manifest.js";
+import { validateModuleComposition } from "./composition.js";
+
+describe("Module Composition 契约", () => {
+  test("校验依赖顺序及所有声明的实现绑定", () => {
+    const system = fixture("system");
+    const business = fixture("business", ["system"]);
+    const result = validateModuleComposition([business, system], {
+      adminRoutes: ["system.page", "business.page"],
+      apiRoutes: ["GET /api/system", "GET /api/business"],
+      tasks: ["system.task", "business.task"],
+      tools: ["system.tool", "business.tool"],
+      providers: ["system.provider", "business.provider"],
+    });
+
+    expect(result.moduleOrder).toEqual(["system", "business"]);
+  });
+
+  test("缺失依赖和循环依赖均 fail-fast", () => {
+    expect(() =>
+      validateModuleComposition([fixture("business", ["missing"])]),
+    ).toThrow("缺少依赖");
+    expect(() =>
+      validateModuleComposition([fixture("a", ["b"]), fixture("b", ["a"])]),
+    ).toThrow("模块依赖存在循环");
+  });
+
+  test("重复能力 Key 会被拒绝", () => {
+    const duplicate = fixture("duplicate");
+    duplicate.permissions[0] = {
+      ...duplicate.permissions[0]!,
+      key: "system.read",
+    };
+    expect(() =>
+      validateModuleComposition([fixture("system"), duplicate]),
+    ).toThrow("权限 Key 重复：system.read");
+  });
+
+  test("未知 Permission、Feature 与 Audit 引用会被拒绝", () => {
+    const permission = fixture("permission");
+    permission.adminRoutes[0]!.permissionKey = "missing.read";
+    expect(() => validateModuleComposition([permission])).toThrow("未注册权限");
+
+    const feature = fixture("feature");
+    feature.apiPermissions[0]!.featureKey = "missing.feature";
+    expect(() => validateModuleComposition([feature])).toThrow(
+      "未注册 Feature",
+    );
+
+    const audit = fixture("audit");
+    audit.tools[0]!.auditAction = "security.denied";
+    expect(() => validateModuleComposition([audit])).toThrow("未注册审计动作");
+  });
+
+  test("菜单 Guard 必须与 Admin Route 一致", () => {
+    const module = fixture("system");
+    module.adminRoutes[0]!.permissionKey = "system.manage";
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Admin Route Guard 不一致",
+    );
+  });
+
+  test("共享管理容器只校验管理面准入，页面入口保留各自 Guard", () => {
+    const module = fixture("system");
+    module.adminRoutes[0] = {
+      ...module.adminRoutes[0]!,
+      directAccess: "admin-admission",
+      permissionKey: "system.manage",
+    };
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+    expect(module.menus[0]).toMatchObject({
+      permissionKey: "system.read",
+      featureKey: "system.feature",
+    });
+  });
+
+  test.each([
+    ["adminRoutes", "Admin Route system.page 缺少 Handler"],
+    ["apiRoutes", "API Route GET /api/system 缺少 Handler"],
+    ["tasks", "定时任务 system.task 缺少 Handler"],
+    ["tools", "Agent Tool system.tool 缺少 Handler"],
+    ["providers", "Provider system.provider 缺少 Handler"],
+  ] as const)("缺失 %s 实现时 fail-fast", (surface, message) => {
+    expect(() =>
+      validateModuleComposition([fixture("system")], { [surface]: [] }),
+    ).toThrow(message);
+  });
+
+  test("Schema Export 无 Migration 证据时被拒绝", () => {
+    const module = fixture("system");
+    module.schemaExports[0]!.migrationIds = [];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Schema Export system.schema 缺少 Migration",
+    );
+  });
+
+  test("字段治理策略校验唯一资源、权限风险和已注册字段", () => {
+    const module = fixture("system");
+    module.permissions.push({
+      ...permission("system", "system.reveal", "manage"),
+      action: "reveal",
+      accessRisk: "sensitive-disclosure",
+    });
+    module.permissions.push({
+      ...permission("system", "system.export", "manage"),
+      action: "export",
+      accessRisk: "governed-export",
+    });
+    module.dataPolicies = [dataPolicy()];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+
+    module.dataPolicies[0]!.fields.push(module.dataPolicies[0]!.fields[0]!);
+    expect(() => validateModuleComposition([module])).toThrow(
+      "字段 Key 重复：phone",
+    );
+  });
+
+  test("字段治理策略拒绝普通权限冒充 reveal 或 governed export", () => {
+    const module = fixture("system");
+    module.dataPolicies = [dataPolicy()];
+    expect(() => validateModuleComposition([module])).toThrow("未注册权限");
+
+    module.dataPolicies[0]!.revealPermissionKey = "system.manage";
+    module.dataPolicies[0]!.exportPermissionKey = "system.manage";
+    expect(() => validateModuleComposition([module])).toThrow(
+      "明文权限必须标记 sensitive-disclosure",
+    );
+  });
+});
+
+function fixture(name: string, dependencies: string[] = []): ModuleManifest {
+  const featureKey = `${name}.feature`;
+  const readPermission = `${name}.read`;
+  const managePermission = `${name}.manage`;
+  return {
+    name,
+    version: "0.1.0",
+    label: name,
+    description: `${name} module`,
+    dependencies,
+    menus: [
+      {
+        key: `${name}.page`,
+        title: name,
+        type: "menu",
+        order: 1,
+        visible: true,
+        path: `/${name}`,
+        permissionKey: readPermission,
+        featureKey,
+      },
+    ],
+    adminRoutes: [
+      {
+        key: `${name}.page`,
+        path: `/${name}`,
+        title: name,
+        surface: "sidebar",
+        permissionKey: readPermission,
+        featureKey,
+      },
+    ],
+    permissions: [
+      permission(name, readPermission, "read"),
+      permission(name, managePermission, "manage"),
+    ],
+    apiPermissions: [
+      {
+        method: "GET",
+        path: `/api/${name}`,
+        permissionKey: readPermission,
+        featureKey,
+      },
+    ],
+    features: [
+      {
+        key: featureKey,
+        label: name,
+        module: name,
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [
+      {
+        key: `${name}.schema`,
+        exportName: `${name}Table`,
+        migrationIds: [`${name}.001`],
+      },
+    ],
+    tasks: [
+      {
+        key: `${name}.task`,
+        label: name,
+        description: name,
+        permissionKey: managePermission,
+        featureKey,
+        intervalSeconds: 60,
+        maxAttempts: 3,
+        retryDelaySeconds: 10,
+      },
+    ],
+    tools: [
+      {
+        key: `${name}.tool`,
+        label: name,
+        description: name,
+        permissionKey: readPermission,
+        featureKey,
+        auditAction: "agent.tool.execute",
+      },
+    ],
+    providers: [
+      {
+        key: `${name}.provider`,
+        kind: "fixture",
+        contractVersion: "1",
+        permissionKey: readPermission,
+        featureKey,
+      },
+    ],
+    auditActions: ["agent.tool.execute"],
+  };
+}
+
+function dataPolicy(): NonNullable<ModuleManifest["dataPolicies"]>[number] {
+  return {
+    key: "system.user.fields",
+    resourceType: "system.user",
+    version: "1",
+    featureKey: featureKey("system.feature"),
+    readPermissionKey: "system.read",
+    revealPermissionKey: "system.reveal",
+    exportPermissionKey: "system.export",
+    display: {
+      read: "masked",
+      reveal: "plaintext",
+      unauthorized: "hidden",
+    },
+    fields: [
+      {
+        fieldKey: "phone",
+        classification: "sensitive",
+        mask: { kind: "partial", prefix: 3, suffix: 4 },
+      },
+    ],
+  };
+}
+
+function permission(
+  module: string,
+  key: string,
+  action: "read" | "manage",
+): ModuleManifest["permissions"][number] {
+  return {
+    key,
+    label: action,
+    module,
+    resource: "fixture",
+    action,
+  };
+}

package/template/packages/modules/src/composition.ts

@@ -0,0 +1,342 @@
+import type { MenuNode } from "@windy/shared";
+import type {
+  ModuleImplementationBindings,
+  ModuleManifest,
+} from "./manifest.js";
+import { composeModuleMenus } from "./menu-composition.js";
+
+export interface ValidatedModuleComposition {
+  modules: readonly ModuleManifest[];
+  moduleOrder: readonly string[];
+}
+
+export function apiRouteKey(input: { method: string; path: string }): string {
+  return `${input.method.toUpperCase()} ${input.path}`;
+}
+
+export function validateModuleComposition(
+  modules: readonly ModuleManifest[],
+  implementations: ModuleImplementationBindings = {},
+): ValidatedModuleComposition {
+  const moduleNames = unique(
+    "模块",
+    modules.map(({ name }) => name),
+  );
+  const moduleOrder = validateDependencies(modules, moduleNames);
+  const permissions = unique(
+    "权限",
+    modules.flatMap((module) => module.permissions.map(({ key }) => key)),
+  );
+  const features = unique(
+    "Feature",
+    modules.flatMap((module) => module.features.map(({ key }) => key)),
+  );
+  const audits = new Set(modules.flatMap((module) => module.auditActions));
+  const menus = composeModuleMenus(modules).flatMap((menu) =>
+    flattenMenus([menu]),
+  );
+  unique(
+    "菜单",
+    menus.map(({ key }) => key),
+  );
+  const adminRoutes = modules.flatMap((module) => module.adminRoutes);
+  unique(
+    "Admin Route",
+    adminRoutes.map(({ key }) => key),
+  );
+  unique(
+    "Admin Route 路径",
+    adminRoutes.map(({ path }) => path),
+  );
+  const apiRoutes = modules.flatMap((module) => module.apiPermissions);
+  unique("API Route", apiRoutes.map(apiRouteKey));
+  const tasks = modules.flatMap((module) => module.tasks);
+  unique(
+    "定时任务",
+    tasks.map(({ key }) => key),
+  );
+  const tools = modules.flatMap((module) => module.tools);
+  unique(
+    "Agent Tool",
+    tools.map(({ key }) => key),
+  );
+  const providers = modules.flatMap((module) => module.providers);
+  unique(
+    "Provider",
+    providers.map(({ key }) => key),
+  );
+  const dataPolicies = modules.flatMap((module) => module.dataPolicies || []);
+  unique(
+    "数据治理策略",
+    dataPolicies.map(({ key }) => key),
+  );
+  unique(
+    "数据治理资源",
+    dataPolicies.map(({ resourceType }) => resourceType),
+  );
+  const schemas = modules.flatMap((module) => module.schemaExports);
+  unique(
+    "Schema Export",
+    schemas.map(({ key }) => key),
+  );
+  unique(
+    "Migration",
+    modules.flatMap((module) => module.migrations.map(({ id }) => id)),
+  );
+
+  for (const module of modules) {
+    validateReferences(module, permissions, features, audits);
+    validateDataPolicies(module, modules);
+  }
+  validateMenuRoutes(menus, adminRoutes);
+  validateSchemaMigrations(schemas);
+  validateImplementations(
+    "Admin Route",
+    adminRoutes.map(({ key }) => key),
+    implementations.adminRoutes,
+  );
+  validateImplementations(
+    "API Route",
+    apiRoutes.map(apiRouteKey),
+    implementations.apiRoutes,
+  );
+  validateImplementations(
+    "定时任务",
+    tasks.map(({ key }) => key),
+    implementations.tasks,
+  );
+  validateImplementations(
+    "Agent Tool",
+    tools.map(({ key }) => key),
+    implementations.tools,
+  );
+  validateImplementations(
+    "Provider",
+    providers.map(({ key }) => key),
+    implementations.providers,
+  );
+
+  return { modules, moduleOrder };
+}
+
+function validateDataPolicies(
+  module: ModuleManifest,
+  modules: readonly ModuleManifest[],
+): void {
+  const permissionByKey = new Map(
+    modules.flatMap((item) =>
+      item.permissions.map(
+        (permission) => [permission.key, permission] as const,
+      ),
+    ),
+  );
+  const featureKeys = new Set(
+    modules.flatMap((item) => item.features.map(({ key }) => key)),
+  );
+  for (const policy of module.dataPolicies || []) {
+    if (
+      !policy.key.trim() ||
+      !policy.resourceType.trim() ||
+      !policy.version.trim()
+    ) {
+      throw new Error("数据治理策略 Key、资源和版本不能为空");
+    }
+    if (!featureKeys.has(policy.featureKey)) {
+      throw new Error(
+        `${policy.key} 引用了未注册 Feature：${policy.featureKey}`,
+      );
+    }
+    const read = requiredPermission(
+      policy.key,
+      policy.readPermissionKey,
+      permissionByKey,
+    );
+    const reveal = requiredPermission(
+      policy.key,
+      policy.revealPermissionKey,
+      permissionByKey,
+    );
+    const exportPermission = requiredPermission(
+      policy.key,
+      policy.exportPermissionKey,
+      permissionByKey,
+    );
+    if (
+      read.action !== "read" ||
+      (read.accessRisk && read.accessRisk !== "standard")
+    ) {
+      throw new Error(`${policy.key} 普通读取权限必须是 standard read`);
+    }
+    if (
+      reveal.action !== "reveal" ||
+      reveal.accessRisk !== "sensitive-disclosure"
+    ) {
+      throw new Error(`${policy.key} 明文权限必须标记 sensitive-disclosure`);
+    }
+    if (
+      exportPermission.action !== "export" ||
+      exportPermission.accessRisk !== "governed-export"
+    ) {
+      throw new Error(`${policy.key} 导出权限必须标记 governed-export`);
+    }
+    if (!policy.fields.length)
+      throw new Error(`${policy.key} 至少治理一个字段`);
+    unique(
+      `${policy.key} 字段`,
+      policy.fields.map(({ fieldKey }) => fieldKey),
+    );
+    for (const field of policy.fields) validateGovernedField(policy.key, field);
+  }
+}
+
+function requiredPermission(
+  policyKey: string,
+  permissionKey: string,
+  definitions: ReadonlyMap<string, ModuleManifest["permissions"][number]>,
+) {
+  const permission = definitions.get(permissionKey);
+  if (!permission) {
+    throw new Error(`${policyKey} 引用了未注册权限：${permissionKey}`);
+  }
+  return permission;
+}
+
+function validateGovernedField(
+  policyKey: string,
+  field: NonNullable<ModuleManifest["dataPolicies"]>[number]["fields"][number],
+) {
+  if (!field.fieldKey.trim()) throw new Error(`${policyKey} 字段 Key 不能为空`);
+  if (field.mask.kind !== "partial") return;
+  if (
+    !Number.isSafeInteger(field.mask.prefix) ||
+    !Number.isSafeInteger(field.mask.suffix) ||
+    field.mask.prefix < 0 ||
+    field.mask.suffix < 0
+  ) {
+    throw new Error(`${policyKey}.${field.fieldKey} 掩码位数必须是非负整数`);
+  }
+}
+
+function validateDependencies(
+  modules: readonly ModuleManifest[],
+  moduleNames: ReadonlySet<string>,
+): string[] {
+  for (const module of modules) {
+    for (const dependency of module.dependencies || []) {
+      if (!moduleNames.has(dependency)) {
+        throw new Error(`模块 ${module.name} 缺少依赖：${dependency}`);
+      }
+    }
+  }
+  const pending = new Map(modules.map((module) => [module.name, module]));
+  const order: string[] = [];
+  while (pending.size) {
+    const ready = [...pending.values()].find((module) =>
+      (module.dependencies || []).every(
+        (dependency) => !pending.has(dependency),
+      ),
+    );
+    if (!ready) throw new Error("模块依赖存在循环");
+    order.push(ready.name);
+    pending.delete(ready.name);
+  }
+  return order;
+}
+
+function validateReferences(
+  module: ModuleManifest,
+  permissions: ReadonlySet<string>,
+  features: ReadonlySet<string>,
+  audits: ReadonlySet<string>,
+): void {
+  const guarded = [
+    ...flattenMenus(module.menus),
+    ...module.adminRoutes,
+    ...module.apiPermissions,
+    ...module.tasks,
+    ...module.tools,
+    ...module.providers,
+  ];
+  for (const item of guarded) {
+    const reference = item as {
+      key?: string;
+      path?: string;
+      permissionKey?: string;
+      featureKey?: string;
+    };
+    const label = reference.key || reference.path || module.name;
+    if (reference.permissionKey && !permissions.has(reference.permissionKey)) {
+      throw new Error(`${label} 引用了未注册权限：${reference.permissionKey}`);
+    }
+    if (reference.featureKey && !features.has(reference.featureKey)) {
+      throw new Error(`${label} 引用了未注册 Feature：${reference.featureKey}`);
+    }
+  }
+  for (const tool of module.tools) {
+    if (!audits.has(tool.auditAction)) {
+      throw new Error(`${tool.key} 引用了未注册审计动作：${tool.auditAction}`);
+    }
+  }
+  for (const migration of module.migrations) {
+    if (migration.module !== module.name) {
+      throw new Error(
+        `Migration ${migration.id} 的模块归属应为 ${module.name}`,
+      );
+    }
+  }
+}
+
+function validateMenuRoutes(
+  menus: readonly MenuNode[],
+  routes: readonly ModuleManifest["adminRoutes"][number][],
+): void {
+  const byPath = new Map(routes.map((route) => [route.path, route]));
+  for (const menu of menus) {
+    if (!menu.path) continue;
+    const route = byPath.get(menu.path);
+    if (!route)
+      throw new Error(`菜单 ${menu.key} 缺少 Admin Route：${menu.path}`);
+    if (
+      route.directAccess !== "admin-admission" &&
+      (route.permissionKey !== menu.permissionKey ||
+        route.featureKey !== menu.featureKey)
+    ) {
+      throw new Error(`菜单 ${menu.key} 与 Admin Route Guard 不一致`);
+    }
+  }
+}
+
+function validateSchemaMigrations(
+  schemas: readonly ModuleManifest["schemaExports"][number][],
+): void {
+  for (const schema of schemas) {
+    if (!schema.migrationIds.length) {
+      throw new Error(`Schema Export ${schema.key} 缺少 Migration`);
+    }
+  }
+}
+
+function validateImplementations(
+  label: string,
+  declarations: readonly string[],
+  implementations: readonly string[] | undefined,
+): void {
+  if (!implementations) return;
+  const registered = unique(`${label} Handler`, implementations);
+  for (const key of declarations) {
+    if (!registered.has(key)) throw new Error(`${label} ${key} 缺少 Handler`);
+  }
+}
+
+function unique(label: string, values: readonly string[]): Set<string> {
+  const result = new Set<string>();
+  for (const value of values) {
+    if (result.has(value)) throw new Error(`${label} Key 重复：${value}`);
+    result.add(value);
+  }
+  return result;
+}
+
+function flattenMenus(menus: readonly MenuNode[]): MenuNode[] {
+  return menus.flatMap((menu) => [menu, ...flattenMenus(menu.children || [])]);
+}

package/template/packages/modules/src/installed-business-modules.ts

@@ -0,0 +1,10 @@
+// @windy-module work-order begin
+import { workOrderModule } from "@windy/example-work-order";
+// @windy-module work-order end
+import type { ModuleFactory } from "./manifest.js";
+
+export const installedBusinessModuleFactories: ModuleFactory[] = [
+  // @windy-module work-order begin
+  workOrderModule,
+  // @windy-module work-order end
+];

package/template/packages/modules/src/manifest.ts

@@ -0,0 +1,97 @@
+import type {
+  ApiPermissionBinding,
+  AuditActionType,
+  DataGovernancePolicyDefinition,
+  FeatureFlagDefinition,
+  MigrationExecutionContext,
+  MenuNode,
+  PermissionDefinition,
+  SearchProviderManifestDefinition,
+} from "@windy/shared";
+
+export type MigrationDirection = "up" | "down";
+
+export interface MigrationDefinition {
+  id: string;
+  module: string;
+  description: string;
+  direction: MigrationDirection;
+  run(context: MigrationExecutionContext): Promise<void>;
+}
+
+export interface ModuleToolDefinition {
+  key: string;
+  label: string;
+  description: string;
+  permissionKey: string;
+  featureKey?: string;
+  auditAction: AuditActionType;
+}
+
+export type AdminRouteSurface = "sidebar" | "account" | "hidden";
+
+export interface ModuleAdminRouteDefinition {
+  key: string;
+  path: string;
+  title: string;
+  surface: AdminRouteSurface;
+  directAccess?: "guarded" | "admin-admission" | "authenticated";
+  permissionKey?: string;
+  featureKey?: string;
+}
+
+export interface ModuleProviderDefinition {
+  key: string;
+  kind: string;
+  contractVersion: string;
+  permissionKey?: string;
+  featureKey?: string;
+}
+
+export interface ModuleSchemaExportDefinition {
+  key: string;
+  exportName: string;
+  migrationIds: readonly string[];
+}
+
+export interface ModuleScheduledTaskDefinition {
+  key: string;
+  label: string;
+  description: string;
+  permissionKey: string;
+  featureKey: string;
+  intervalSeconds: number;
+  maxAttempts: number;
+  retryDelaySeconds: number;
+}
+
+export interface ModuleManifest {
+  name: string;
+  version: string;
+  label: string;
+  description: string;
+  dependencies?: string[];
+  menus: MenuNode[];
+  adminRoutes: ModuleAdminRouteDefinition[];
+  permissions: PermissionDefinition[];
+  apiPermissions: ApiPermissionBinding[];
+  features: FeatureFlagDefinition[];
+  migrations: MigrationDefinition[];
+  schemaExports: ModuleSchemaExportDefinition[];
+  tasks: ModuleScheduledTaskDefinition[];
+  tools: ModuleToolDefinition[];
+  providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
+  dataPolicies?: DataGovernancePolicyDefinition[];
+  auditActions: AuditActionType[];
+  metadata?: Record<string, unknown>;
+}
+
+export type ModuleFactory = () => ModuleManifest;
+
+export interface ModuleImplementationBindings {
+  adminRoutes?: readonly string[];
+  apiRoutes?: readonly string[];
+  tasks?: readonly string[];
+  tools?: readonly string[];
+  providers?: readonly string[];
+}