create-windy 0.3.18 → 0.4.0

package/template/packages/modules/src/admin-ui-manifest.ts

@@ -0,0 +1,53 @@
+import type { ModuleAdminRouteDefinition, ModuleManifest } from "./manifest.js";
+
+/**
+ * 浏览器可见的最小 Module 契约。Server Manifest 的 Migration、Task、Provider、
+ * Audit 和持久化元数据不得进入这个类型或 Web bundle。
+ */
+export interface AdminUiManifest {
+  readonly name: string;
+  readonly version: string;
+  readonly adminRoutes: readonly ModuleAdminRouteDefinition[];
+}
+
+export type AdminPageLoader<TPage = unknown> = () => Promise<{
+  readonly default: TPage;
+}>;
+
+export interface AdminPageBinding<TPage = unknown> {
+  readonly routeKey: string;
+  readonly load: AdminPageLoader<TPage>;
+}
+
+export interface WindyAdminUiModule<TPage = unknown> {
+  readonly manifest: AdminUiManifest;
+  readonly hostRange: string;
+  readonly pages: readonly AdminPageBinding<TPage>[];
+}
+
+export type AdminUiManifestSource = Pick<
+  ModuleManifest,
+  "name" | "version" | "adminRoutes"
+>;
+
+export function defineAdminUiManifest(
+  manifest: AdminUiManifest,
+): AdminUiManifest {
+  return manifest;
+}
+
+export function defineWindyAdminUiModule<TPage>(
+  module: WindyAdminUiModule<TPage>,
+): WindyAdminUiModule<TPage> {
+  return module;
+}
+
+export function projectAdminUiManifest(
+  manifest: AdminUiManifestSource,
+): AdminUiManifest {
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    adminRoutes: manifest.adminRoutes.map((route) => ({ ...route })),
+  };
+}

package/template/packages/modules/src/capability-audit-validation.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, test } from "bun:test";
+import { fixture } from "./composition-fixtures.test-support.js";
+import { validateModuleComposition } from "./composition.js";
+import { systemFoundationModule } from "./system-modules.js";
+
+describe("API 与定时任务 Audit Action 组合门禁", () => {
+  test("非匿名 API 缺少 Audit Action 时 fail closed", () => {
+    const module = fixture("api-audit");
+    Reflect.deleteProperty(module.apiPermissions[0]!, "auditAction");
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      "API Route GET /api/api-audit 必须声明 Audit Action",
+    );
+  });
+
+  test("定时任务缺少 Audit Action 时 fail closed", () => {
+    const module = fixture("task-audit");
+    Reflect.deleteProperty(module.tasks[0]!, "auditAction");
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      "定时任务 task-audit.task 必须声明 Audit Action",
+    );
+  });
+
+  test.each([
+    [
+      "API Route GET /api/api-audit",
+      (module: ReturnType<typeof fixture>) => {
+        module.apiPermissions[0]!.auditAction = "audit.unknown";
+      },
+    ],
+    [
+      "定时任务 task-audit.task",
+      (module: ReturnType<typeof fixture>) => {
+        module.tasks[0]!.auditAction = "audit.unknown";
+      },
+    ],
+  ] as const)("%s 引用未知 Audit Action 时 fail closed", (label, mutate) => {
+    const module = fixture(
+      label.startsWith("API") ? "api-audit" : "task-audit",
+    );
+    mutate(module);
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      `${label} 引用了未注册审计动作：audit.unknown`,
+    );
+  });
+
+  test("显式匿名 API 可以不声明 Audit Action", () => {
+    const module = fixture("public");
+    module.apiPermissions[0]!.anonymous = true;
+    Reflect.deleteProperty(module.apiPermissions[0]!, "auditAction");
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
+  test("Provider 不虚构执行 Audit Action", () => {
+    const module = fixture("provider");
+
+    expect("auditAction" in module.providers[0]!).toBe(false);
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
+  test("系统 API 与任务引用的 Audit Action 均由 Manifest 注册", () => {
+    const manifest = systemFoundationModule();
+    const registered = new Set(
+      manifest.auditActions.map((action) =>
+        typeof action === "string" ? action : action.key,
+      ),
+    );
+    const used = [
+      ...manifest.apiPermissions
+        .filter(({ anonymous }) => anonymous !== true)
+        .map(({ auditAction }) => auditAction),
+      ...manifest.tasks.map(({ auditAction }) => auditAction),
+    ];
+
+    expect(used.every((action) => action && registered.has(action))).toBe(true);
+  });
+
+  test("系统资源 API 按读取、导入、导出和 CRUD 语义声明 Audit Action", () => {
+    const bindings = systemFoundationModule().apiPermissions.filter(
+      ({ path }) => path.startsWith("/api/system/roles"),
+    );
+
+    expect(bindings.map(({ auditAction }) => auditAction)).toEqual([
+      "data.read",
+      "data.export",
+      "data.read",
+      "data.import",
+      "crud.create",
+      "crud.update",
+      "crud.delete",
+    ]);
+  });
+
+  test.each([
+    // @windy-module system.search begin
+    ["POST", "/api/search", "search.query"],
+    // @windy-module system.search end
+    ["PUT", "/api/system/menus/placements", "menu.structure.update"],
+    ["PUT", "/api/system/features/:id", "feature.update"],
+    // @windy-module system.scheduler begin
+    ["POST", "/api/system/scheduled-tasks/:id/trigger", "task.trigger"],
+    // @windy-module system.scheduler end
+    // @windy-module system.bulk-data begin
+    [
+      "POST",
+      "/api/system/bulk-data/dictionaries/import",
+      "data.bulk-import.create",
+    ],
+    // @windy-module system.bulk-data end
+    // @windy-module system.storage begin
+    [
+      "PUT",
+      "/api/system/storage/uploads/:id/parts/:partNumber",
+      "file.upload.part.write",
+    ],
+    // @windy-module system.storage end
+  ] as const)("%s %s 声明真实动作 %s", (method, path, auditAction) => {
+    expect(
+      systemFoundationModule().apiPermissions.find(
+        (binding) => binding.method === method && binding.path === path,
+      ),
+    ).toMatchObject({ auditAction });
+  });
+});

package/template/packages/modules/src/capability-audit-validation.ts

@@ -0,0 +1,38 @@
+import type { AuditActionType } from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+export function validateCapabilityAuditActions(
+  modules: readonly ModuleManifest[],
+  auditActions: ReadonlySet<string>,
+): void {
+  for (const module of modules) {
+    for (const route of module.apiPermissions) {
+      if (route.anonymous === true) continue;
+      validateAuditAction(
+        `API Route ${route.method} ${route.path}`,
+        route.auditAction,
+        auditActions,
+      );
+    }
+    for (const task of module.tasks) {
+      validateAuditAction(
+        `定时任务 ${task.key}`,
+        task.auditAction,
+        auditActions,
+      );
+    }
+  }
+}
+
+function validateAuditAction(
+  label: string,
+  auditAction: AuditActionType | undefined,
+  auditActions: ReadonlySet<string>,
+): void {
+  if (!auditAction?.trim()) {
+    throw new Error(`${label} 必须声明 Audit Action`);
+  }
+  if (!auditActions.has(auditAction)) {
+    throw new Error(`${label} 引用了未注册审计动作：${auditAction}`);
+  }
+}

package/template/packages/modules/src/capability-guard-validation.ts

@@ -0,0 +1,148 @@
+import type { MenuNode } from "@southwind-ai/shared";
+import type { ModuleManifest } from "./manifest.js";
+
+interface CapabilityGuard {
+  label: string;
+  permissionKey?: string;
+  featureKey?: string;
+}
+
+export function validateCapabilityGuardCompleteness(
+  modules: readonly ModuleManifest[],
+): void {
+  for (const module of modules) {
+    const guards: CapabilityGuard[] = [
+      ...flattenMenus(module.menus)
+        .filter(({ type }) => type !== "catalog")
+        .map((menu) => guard("菜单", menu)),
+      ...module.adminRoutes.map((route) => guard("Admin Route", route)),
+      ...module.apiPermissions
+        .filter(({ anonymous }) => anonymous !== true)
+        .map((route) =>
+          guard("API Route", {
+            ...route,
+            key: `${route.method} ${route.path}`,
+          }),
+        ),
+      ...module.tasks.map((task) => guard("定时任务", task)),
+      ...module.tools.map((tool) => guard("Agent Tool", tool)),
+      ...(module.aiOperations || []).map((operation) =>
+        guard("AI Operation", operation),
+      ),
+      ...module.providers.map((provider) => guard("Provider", provider)),
+    ];
+
+    for (const item of guards) {
+      if (!item.permissionKey?.trim() || !item.featureKey?.trim()) {
+        throw new Error(`${item.label} 必须同时声明 Permission 与 Feature`);
+      }
+    }
+  }
+}
+
+export function validateCapabilityKeyAlignment(
+  modules: readonly ModuleManifest[],
+): void {
+  const featureKeys = new Set<string>(
+    modules.flatMap((module) => module.features.map(({ key }) => key)),
+  );
+  const permissionKeys = new Set(
+    modules.flatMap((module) => module.permissions.map(({ key }) => key)),
+  );
+
+  for (const module of modules) {
+    for (const permission of module.permissions) {
+      const expectedFeatureKey = permissionFeatureKey(permission.key);
+      if (!featureKeys.has(expectedFeatureKey)) {
+        throw new Error(
+          `权限 ${permission.key} 缺少同基础 Key Feature：${expectedFeatureKey}`,
+        );
+      }
+    }
+
+    const guards: CapabilityGuard[] = [
+      ...flattenMenus(module.menus)
+        .filter(({ type }) => type !== "catalog")
+        .map((menu) => guard("菜单", menu)),
+      ...module.adminRoutes.map((route) => guard("Admin Route", route)),
+      ...module.apiPermissions
+        .filter(({ anonymous }) => anonymous !== true)
+        .map((route) =>
+          guard("API Route", {
+            ...route,
+            key: `${route.method} ${route.path}`,
+          }),
+        ),
+      ...module.tasks.map((task) => guard("定时任务", task)),
+      ...module.tools.map((tool) => guard("Agent Tool", tool)),
+      ...(module.aiOperations || []).map((operation) =>
+        guard("AI Operation", operation),
+      ),
+      ...module.providers.map((provider) => guard("Provider", provider)),
+      ...(module.dataPolicies || []).flatMap((policy) =>
+        [
+          policy.readPermissionKey,
+          policy.revealPermissionKey,
+          policy.exportPermissionKey,
+        ].map((permissionKey) =>
+          guard("数据治理策略", {
+            key: policy.key,
+            permissionKey,
+            featureKey: policy.featureKey,
+          }),
+        ),
+      ),
+    ];
+
+    for (const item of guards) {
+      validateKeyAlignment(item.label, item, permissionKeys, featureKeys);
+    }
+  }
+}
+
+function validateKeyAlignment(
+  label: string,
+  input: { permissionKey?: string; featureKey?: string },
+  permissionKeys: ReadonlySet<string>,
+  featureKeys: ReadonlySet<string>,
+): void {
+  if (
+    !input.permissionKey ||
+    !input.featureKey ||
+    !permissionKeys.has(input.permissionKey) ||
+    !featureKeys.has(input.featureKey)
+  ) {
+    return;
+  }
+  const expectedFeatureKey = permissionFeatureKey(input.permissionKey);
+  if (input.featureKey !== expectedFeatureKey) {
+    throw new Error(
+      `${label} 的 Permission 基础 Key ${expectedFeatureKey} 与 Feature ${input.featureKey} 不一致`,
+    );
+  }
+}
+
+function permissionFeatureKey(permissionKey: string): string {
+  const separator = permissionKey.lastIndexOf(".");
+  return separator > 0 ? permissionKey.slice(0, separator) : "";
+}
+
+function guard(
+  kind: string,
+  input: {
+    key?: string;
+    path?: string;
+    permissionKey?: string;
+    featureKey?: string;
+  },
+): CapabilityGuard {
+  return {
+    label: `${kind} ${input.key || input.path || "unknown"}`,
+    permissionKey: input.permissionKey,
+    featureKey: input.featureKey,
+  };
+}
+
+function flattenMenus(menus: readonly MenuNode[]): MenuNode[] {
+  return menus.flatMap((menu) => [menu, ...flattenMenus(menu.children || [])]);
+}

package/template/packages/modules/src/capability-key-validation.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import {
+  dataPolicy,
+  fixture,
+  permission,
+} from "./composition-fixtures.test-support.js";
+import { validateModuleComposition } from "./composition.js";
+import type { ModuleManifest } from "./manifest.js";
+import userModule from "../user/module.js";
+
+describe("Capability 基础 Key 组合门禁", () => {
+  test("Permission 缺少同基础 Key Feature 时 fail closed", () => {
+    const module = fixture("permission");
+    module.permissions.push(
+      permission("permission", "permission.orphan.read", "read"),
+    );
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      "权限 permission.orphan.read 缺少同基础 Key Feature：permission.orphan",
+    );
+  });
+
+  test.each([
+    [
+      "菜单 binding.page",
+      (module: ModuleManifest) => {
+        module.menus[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "Admin Route binding.page",
+      (module: ModuleManifest) => {
+        module.adminRoutes[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "API Route GET /api/binding",
+      (module: ModuleManifest) => {
+        module.apiPermissions[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "定时任务 binding.task",
+      (module: ModuleManifest) => {
+        module.tasks[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "Agent Tool binding.tool",
+      (module: ModuleManifest) => {
+        module.tools[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "AI Operation binding.ai-operation",
+      (module: ModuleManifest) => {
+        module.aiOperations = [aiOperation()];
+      },
+    ],
+    [
+      "Provider binding.provider",
+      (module: ModuleManifest) => {
+        module.providers[0]!.featureKey = featureKey("binding.other");
+      },
+    ],
+    [
+      "数据治理策略 binding.feature.fields",
+      (module: ModuleManifest) => {
+        addDataPolicy(module);
+      },
+    ],
+  ] as const)("%s 的 Guard 基础 Key 漂移时 fail closed", (label, mutate) => {
+    const module = fixture("binding");
+    module.features.push({
+      ...module.features[0]!,
+      key: featureKey("binding.other"),
+    });
+    mutate(module);
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      `${label} 的 Permission 基础 Key binding.feature 与 Feature binding.other 不一致`,
+    );
+  });
+
+  test("显式匿名 API 不要求 Permission 与 Feature 使用同一基础 Key", () => {
+    const module = fixture("public");
+    module.features.push({
+      ...module.features[0]!,
+      key: featureKey("public.other"),
+    });
+    module.apiPermissions[0]!.anonymous = true;
+    module.apiPermissions[0]!.featureKey = featureKey("public.other");
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
+  test("示例用户模块通过完整 Capability Guard 门禁", () => {
+    expect(() => validateModuleComposition([userModule()])).not.toThrow();
+  });
+});
+
+function aiOperation(): NonNullable<ModuleManifest["aiOperations"]>[number] {
+  return {
+    key: "binding.ai-operation",
+    kind: "agent",
+    featureKey: featureKey("binding.other"),
+    permissionKey: "binding.feature.read",
+    auditAction: "agent.tool.execute",
+    inputSchemaKey: "binding.tool.input.v1",
+    outputSchemaKey: "binding.tool.output.v1",
+    requiredCapabilities: ["text-generation"],
+    allowedToolKeys: [],
+    dataClassification: "internal",
+    execution: "interactive",
+    providerEgress: { mode: "forbidden" },
+    toolNetworkPolicy: { mode: "forbidden" },
+    limits: {
+      maxDurationSeconds: 10,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 4_096,
+    },
+  };
+}
+
+function addDataPolicy(module: ModuleManifest): void {
+  module.permissions.push(
+    {
+      ...permission("binding", "binding.feature.reveal", "manage"),
+      action: "reveal",
+      accessRisk: "sensitive-disclosure",
+    },
+    {
+      ...permission("binding", "binding.feature.export", "manage"),
+      action: "export",
+      accessRisk: "governed-export",
+    },
+  );
+  module.dataPolicies = [
+    {
+      ...dataPolicy(),
+      key: "binding.feature.fields",
+      resourceType: "binding.feature",
+      featureKey: featureKey("binding.other"),
+      readPermissionKey: "binding.feature.read",
+      revealPermissionKey: "binding.feature.reveal",
+      exportPermissionKey: "binding.feature.export",
+    },
+  ];
+}

package/template/packages/modules/src/composition-fixtures.test-support.ts

@@ -6,8 +6,8 @@ export function fixture(
   dependencies: string[] = [],
 ): ModuleManifest {
   const featureKey = `${name}.feature`;
-  const readPermission = `${name}.read`;
-  const managePermission = `${name}.manage`;
+  const readPermission = `${featureKey}.read`;
+  const managePermission = `${featureKey}.manage`;
   return {
     name,
     version: "0.1.0",
@@ -46,6 +46,7 @@ export function fixture(
         path: `/api/${name}`,
         permissionKey: readPermission,
         featureKey,
+        auditAction: "data.search",
       },
     ],
     features: [
@@ -83,6 +84,7 @@ export function fixture(
         description: name,
         permissionKey: managePermission,
         featureKey,
+        auditAction: "task.execute",
         intervalSeconds: 60,
         maxAttempts: 3,
         retryDelaySeconds: 10,
@@ -131,9 +133,9 @@ export function dataPolicy(): NonNullable<
     resourceType: "system.user",
     version: "1",
     featureKey: featureKey("system.feature"),
-    readPermissionKey: "system.read",
-    revealPermissionKey: "system.reveal",
-    exportPermissionKey: "system.export",
+    readPermissionKey: "system.feature.read",
+    revealPermissionKey: "system.feature.reveal",
+    exportPermissionKey: "system.feature.export",
     display: {
       read: "masked",
       reveal: "plaintext",

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

@@ -35,11 +35,11 @@ describe("Module Composition 契约", () => {
     const duplicate = fixture("duplicate");
     duplicate.permissions[0] = {
       ...duplicate.permissions[0]!,
-      key: "system.read",
+      key: "system.feature.read",
     };
     expect(() =>
       validateModuleComposition([fixture("system"), duplicate]),
-    ).toThrow("权限 Key 重复：system.read");
+    ).toThrow("权限 Key 重复：system.feature.read");
   });
 
   test("未知 Permission、Feature 与 Audit 引用会被拒绝", () => {
@@ -58,6 +58,71 @@ describe("Module Composition 契约", () => {
     expect(() => validateModuleComposition([audit])).toThrow("未注册审计动作");
   });
 
+  test.each([
+    [
+      "菜单",
+      (module: ReturnType<typeof fixture>) => {
+        module.menus[0]!.path = undefined;
+        module.menus[0]!.featureKey = undefined;
+      },
+    ],
+    [
+      "Admin Route",
+      (module: ReturnType<typeof fixture>) => {
+        module.menus = [];
+        module.adminRoutes[0]!.featureKey = undefined;
+      },
+    ],
+    [
+      "API Route",
+      (module: ReturnType<typeof fixture>) => {
+        module.apiPermissions[0]!.featureKey = undefined;
+      },
+    ],
+    [
+      "定时任务",
+      (module: ReturnType<typeof fixture>) => {
+        Reflect.deleteProperty(module.tasks[0]!, "featureKey");
+      },
+    ],
+    [
+      "Agent Tool",
+      (module: ReturnType<typeof fixture>) => {
+        Reflect.deleteProperty(module.tools[0]!, "featureKey");
+      },
+    ],
+    [
+      "Provider",
+      (module: ReturnType<typeof fixture>) => {
+        module.providers[0]!.featureKey = undefined;
+      },
+    ],
+  ] as const)("%s 缺少 Feature Guard 时 fail closed", (_, removeFeature) => {
+    const module = fixture("guard");
+    removeFeature(module);
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      "必须同时声明 Permission 与 Feature",
+    );
+  });
+
+  test("业务入口缺少 Permission Guard 时 fail closed", () => {
+    const module = fixture("guard");
+    Reflect.deleteProperty(module.apiPermissions[0]!, "permissionKey");
+
+    expect(() => validateModuleComposition([module])).toThrow(
+      "必须同时声明 Permission 与 Feature",
+    );
+  });
+
+  test("显式匿名 API 可以不声明 Feature Guard", () => {
+    const module = fixture("public");
+    module.apiPermissions[0]!.anonymous = true;
+    module.apiPermissions[0]!.featureKey = undefined;
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+  });
+
   test("业务模块可注册带展示信息的审计动作目录", () => {
     const module = fixture("ticket");
     module.auditActions.push({
@@ -133,7 +198,7 @@ describe("Module Composition 契约", () => {
 
   test("菜单 Guard 必须与 Admin Route 一致", () => {
     const module = fixture("system");
-    module.adminRoutes[0]!.permissionKey = "system.manage";
+    module.adminRoutes[0]!.permissionKey = "system.feature.manage";
     expect(() => validateModuleComposition([module])).toThrow(
       "Admin Route Guard 不一致",
     );
@@ -144,12 +209,12 @@ describe("Module Composition 契约", () => {
     module.adminRoutes[0] = {
       ...module.adminRoutes[0]!,
       directAccess: "admin-admission",
-      permissionKey: "system.manage",
+      permissionKey: "system.feature.manage",
     };
 
     expect(() => validateModuleComposition([module])).not.toThrow();
     expect(module.menus[0]).toMatchObject({
-      permissionKey: "system.read",
+      permissionKey: "system.feature.read",
       featureKey: "system.feature",
     });
   });
@@ -197,12 +262,12 @@ describe("Module Composition 契约", () => {
   test("字段治理策略校验唯一资源、权限风险和已注册字段", () => {
     const module = fixture("system");
     module.permissions.push({
-      ...permission("system", "system.reveal", "manage"),
+      ...permission("system", "system.feature.reveal", "manage"),
       action: "reveal",
       accessRisk: "sensitive-disclosure",
     });
     module.permissions.push({
-      ...permission("system", "system.export", "manage"),
+      ...permission("system", "system.feature.export", "manage"),
       action: "export",
       accessRisk: "governed-export",
     });
@@ -220,8 +285,8 @@ describe("Module Composition 契约", () => {
     module.dataPolicies = [dataPolicy()];
     expect(() => validateModuleComposition([module])).toThrow("未注册权限");
 
-    module.dataPolicies[0]!.revealPermissionKey = "system.manage";
-    module.dataPolicies[0]!.exportPermissionKey = "system.manage";
+    module.dataPolicies[0]!.revealPermissionKey = "system.feature.manage";
+    module.dataPolicies[0]!.exportPermissionKey = "system.feature.manage";
     expect(() => validateModuleComposition([module])).toThrow(
       "明文权限必须标记 sensitive-disclosure",
     );