create-windy 0.3.19 → 0.4.0

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

@@ -4,6 +4,11 @@ import type {
   ModuleManifest,
 } from "./manifest.js";
 import { validateAiOperations } from "./ai-operation-composition.js";
+import { validateCapabilityAuditActions } from "./capability-audit-validation.js";
+import {
+  validateCapabilityGuardCompleteness,
+  validateCapabilityKeyAlignment,
+} from "./capability-guard-validation.js";
 import { validateImplementationBindings } from "./implementation-bindings.js";
 import { composeModuleMenus } from "./menu-composition.js";
 import { validateCapabilityCatalogs } from "./catalog-validation.js";
@@ -27,6 +32,7 @@ export function validateModuleComposition(
     modules.map(({ name }) => name),
   );
   const moduleOrder = validateDependencies(modules, moduleNames);
+  validateCapabilityGuardCompleteness(modules);
   const permissions = unique(
     "权限",
     modules.flatMap((module) => module.permissions.map(({ key }) => key)),
@@ -35,9 +41,11 @@ export function validateModuleComposition(
     "Feature",
     modules.flatMap((module) => module.features.map(({ key }) => key)),
   );
+  validateCapabilityKeyAlignment(modules);
   const catalogs = validateCapabilityCatalogs(modules);
   const jsonSchemas = validateToolContracts(modules);
   const audits = new Set(catalogs.auditActions.map(({ key }) => key));
+  validateCapabilityAuditActions(modules, audits);
   const menus = composeModuleMenus(modules).flatMap((menu) =>
     flattenMenus([menu]),
   );

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

@@ -80,6 +80,7 @@ export interface ModuleScheduledTaskDefinition {
   description: string;
   permissionKey: string;
   featureKey: string;
+  auditAction: AuditActionType;
   intervalSeconds: number;
   maxAttempts: number;
   retryDelaySeconds: number;

package/template/packages/modules/src/migration-bundle-validation.test.ts

@@ -41,6 +41,29 @@ describe("Migration Bundle 启动校验", () => {
     expect(() => validateMigrationBundleCatalog([feature, base])).not.toThrow();
   });
 
+  test("Manifest 可声明不参与迁移排序的额外运行时依赖", () => {
+    const module = bundledModule("feature", [
+      migration("feature", "feature.0001"),
+    ]);
+    module.dependencies = ["system"];
+
+    expect(() => validateMigrationBundleCatalog([module])).not.toThrow();
+  });
+
+  test("Bundle 依赖必须先在 Manifest 中声明", () => {
+    const base = bundledModule("base", [migration("base", "base.0001")]);
+    const feature = bundledModule(
+      "feature",
+      [migration("feature", "feature.0001")],
+      ["base"],
+    );
+    feature.dependencies = [];
+
+    expect(() => validateMigrationBundleCatalog([base, feature])).toThrow(
+      "Migration Bundle feature 依赖未在 Manifest 声明：base",
+    );
+  });
+
   test("重复 Migration ID 被拒绝", () => {
     const first = bundledModule("first", [migration("first", "shared.0001")]);
     const second = bundledModule("second", [

package/template/packages/modules/src/module-host-range.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { satisfiesModuleHostRange } from "./module-host-range.js";
+
+describe("Module Host SemVer range", () => {
+  test("exact 忽略 build metadata，但区分 prerelease", () => {
+    expect(satisfiesModuleHostRange("1.2.3+host.7", "1.2.3")).toBeTrue();
+    expect(
+      satisfiesModuleHostRange("1.2.3-beta.2+host.7", "1.2.3-beta.2+module.1"),
+    ).toBeTrue();
+    expect(
+      satisfiesModuleHostRange("1.2.3-beta.2", "1.2.3-beta.1"),
+    ).toBeFalse();
+    expect(satisfiesModuleHostRange("1.2.3-beta.2", "1.2.3")).toBeFalse();
+  });
+
+  test("prerelease 标识按 SemVer 数字和字符串规则排序", () => {
+    expect(
+      satisfiesModuleHostRange("1.2.3-beta.10", "^1.2.3-beta.2"),
+    ).toBeTrue();
+    expect(
+      satisfiesModuleHostRange("1.2.3-beta.2", "^1.2.3-beta.10"),
+    ).toBeFalse();
+    expect(satisfiesModuleHostRange("1.2.3-rc.1", "^1.2.3-beta.9")).toBeTrue();
+    expect(satisfiesModuleHostRange("1.2.3", "^1.2.3-beta.9")).toBeTrue();
+  });
+
+  test("caret 遵循 0.x 的兼容上界", () => {
+    expect(satisfiesModuleHostRange("2.9.9", "^2.1.0")).toBeTrue();
+    expect(satisfiesModuleHostRange("3.0.0", "^2.1.0")).toBeFalse();
+    expect(satisfiesModuleHostRange("0.2.9", "^0.2.3")).toBeTrue();
+    expect(satisfiesModuleHostRange("0.3.0", "^0.2.3")).toBeFalse();
+    expect(satisfiesModuleHostRange("0.0.4", "^0.0.3")).toBeFalse();
+  });
+
+  test("tilde 只允许同一 minor 内升级", () => {
+    expect(satisfiesModuleHostRange("1.2.99", "~1.2.3")).toBeTrue();
+    expect(satisfiesModuleHostRange("1.3.0", "~1.2.3")).toBeFalse();
+    expect(satisfiesModuleHostRange("1.2.2", "~1.2.3")).toBeFalse();
+  });
+
+  test("普通稳定范围不隐式接纳 prerelease", () => {
+    expect(satisfiesModuleHostRange("1.3.0-beta.1", "^1.2.3")).toBeFalse();
+    expect(satisfiesModuleHostRange("1.2.4-beta.1", "~1.2.3")).toBeFalse();
+  });
+
+  test("非法版本或不支持的 range 以中文错误拒绝", () => {
+    expect(() => satisfiesModuleHostRange("1.2", "^1.2.3")).toThrow(
+      "无效 SemVer：1.2",
+    );
+    expect(() => satisfiesModuleHostRange("1.2.3", ">=1.2.0")).toThrow(
+      "不支持的 Module Host range：>=1.2.0",
+    );
+    expect(() => satisfiesModuleHostRange("1.2.3", "^01.2.3")).toThrow(
+      "无效 SemVer：01.2.3",
+    );
+  });
+});

package/template/packages/modules/src/module-host-range.ts

@@ -0,0 +1,125 @@
+interface SemVerIdentifier {
+  readonly numeric: boolean;
+  readonly value: string;
+}
+
+interface SemVer {
+  readonly core: readonly [bigint, bigint, bigint];
+  readonly prerelease: readonly SemVerIdentifier[];
+}
+
+export function satisfiesModuleHostRange(
+  hostVersion: string,
+  range: string,
+): boolean {
+  const current = parseSemVer(hostVersion);
+  const normalizedRange = range.trim();
+  const operator = normalizedRange.startsWith("^")
+    ? "^"
+    : normalizedRange.startsWith("~")
+      ? "~"
+      : "";
+  const versionText = operator ? normalizedRange.slice(1) : normalizedRange;
+
+  if (!operator && !/^\d/.test(versionText)) {
+    throw new Error(`不支持的 Module Host range：${range}`);
+  }
+
+  const minimum = parseSemVer(versionText);
+  if (!operator) return compareSemVer(current, minimum) === 0;
+
+  const maximum = compatibleUpperBound(minimum, operator);
+  if (
+    compareSemVer(current, minimum) < 0 ||
+    compareSemVer(current, maximum) >= 0
+  ) {
+    return false;
+  }
+  if (current.prerelease.length === 0) return true;
+
+  return (
+    minimum.prerelease.length > 0 &&
+    compareCore(current.core, minimum.core) === 0
+  );
+}
+
+function compatibleUpperBound(minimum: SemVer, operator: "^" | "~"): SemVer {
+  const [major, minor, patch] = minimum.core;
+  const core: readonly [bigint, bigint, bigint] =
+    operator === "~"
+      ? [major, minor + 1n, 0n]
+      : major > 0n
+        ? [major + 1n, 0n, 0n]
+        : minor > 0n
+          ? [0n, minor + 1n, 0n]
+          : [0n, 0n, patch + 1n];
+  return { core, prerelease: [] };
+}
+
+function parseSemVer(value: string): SemVer {
+  const normalized = value.trim();
+  const match =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(
+      normalized,
+    );
+  if (!match) throw new Error(`无效 SemVer：${value}`);
+
+  const prerelease = match[4]
+    ? match[4].split(".").map(parsePrereleaseIdentifier)
+    : [];
+  return {
+    core: [BigInt(match[1]!), BigInt(match[2]!), BigInt(match[3]!)],
+    prerelease,
+  };
+}
+
+function parsePrereleaseIdentifier(value: string): SemVerIdentifier {
+  const numeric = /^\d+$/.test(value);
+  if (numeric && value.length > 1 && value.startsWith("0")) {
+    throw new Error(`无效 SemVer prerelease 标识：${value}`);
+  }
+  return { numeric, value };
+}
+
+function compareSemVer(left: SemVer, right: SemVer): number {
+  const coreComparison = compareCore(left.core, right.core);
+  if (coreComparison !== 0) return coreComparison;
+  if (left.prerelease.length === 0) {
+    return right.prerelease.length === 0 ? 0 : 1;
+  }
+  if (right.prerelease.length === 0) return -1;
+
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftIdentifier = left.prerelease[index];
+    const rightIdentifier = right.prerelease[index];
+    if (!leftIdentifier) return -1;
+    if (!rightIdentifier) return 1;
+    const comparison = compareIdentifier(leftIdentifier, rightIdentifier);
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function compareIdentifier(
+  left: SemVerIdentifier,
+  right: SemVerIdentifier,
+): number {
+  if (left.numeric && right.numeric) {
+    return compareBigInt(BigInt(left.value), BigInt(right.value));
+  }
+  if (left.numeric !== right.numeric) return left.numeric ? -1 : 1;
+  return left.value < right.value ? -1 : left.value > right.value ? 1 : 0;
+}
+
+function compareCore(left: SemVer["core"], right: SemVer["core"]): number {
+  for (let index = 0; index < 3; index += 1) {
+    const comparison = compareBigInt(left[index]!, right[index]!);
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function compareBigInt(left: bigint, right: bigint): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/template/packages/modules/src/project-module-assembly.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from "bun:test";
+import {
+  indexProjectModuleAssembly,
+  validateProjectModuleAssembly,
+} from "./project-module-assembly.js";
+
+const validAssembly = {
+  schemaVersion: 1,
+  modules: [
+    {
+      name: "system",
+      package: null,
+      enabled: true,
+      order: 100,
+      admin: { visible: true },
+      config: {},
+    },
+    {
+      name: "work-order",
+      package: "@southwind-ai/example-work-order",
+      enabled: false,
+      order: 200,
+      admin: { visible: false },
+      config: { queue: "default" },
+    },
+  ],
+} as const;
+
+describe("项目 Module 装配清单", () => {
+  test("合法清单通过校验并可按名称索引", () => {
+    const assembly = validateProjectModuleAssembly(validAssembly);
+    const index = indexProjectModuleAssembly(assembly);
+
+    expect(assembly.schemaVersion).toBe(1);
+    expect(index.get("system")).toEqual(validAssembly.modules[0]);
+    expect(index.get("work-order")?.config).toEqual({ queue: "default" });
+  });
+
+  test("只接受 schemaVersion=1 和 Module 数组", () => {
+    expect(() =>
+      validateProjectModuleAssembly({ ...validAssembly, schemaVersion: 2 }),
+    ).toThrow("windy.modules.json schemaVersion 不受支持：2");
+    expect(() =>
+      validateProjectModuleAssembly({ schemaVersion: 1, modules: null }),
+    ).toThrow("windy.modules.json modules 必须是数组");
+  });
+
+  test("名称必须是非空字符串且不能重复", () => {
+    expect(() =>
+      validateProjectModuleAssembly({
+        ...validAssembly,
+        modules: [{ ...validAssembly.modules[0], name: " " }],
+      }),
+    ).toThrow("windy.modules.json Module 名称不能为空");
+    expect(() =>
+      validateProjectModuleAssembly({
+        ...validAssembly,
+        modules: [
+          validAssembly.modules[0],
+          { ...validAssembly.modules[1], name: "system" },
+        ],
+      }),
+    ).toThrow("windy.modules.json Module 重复：system");
+  });
+
+  test("package 只接受 null 或合法 npm package 名称", () => {
+    for (const packageName of [
+      "",
+      "UpperCase",
+      ".hidden",
+      "@scope",
+      "@scope/package/subpath",
+      "has space",
+    ]) {
+      expect(() =>
+        validateProjectModuleAssembly({
+          ...validAssembly,
+          modules: [{ ...validAssembly.modules[0], package: packageName }],
+        }),
+      ).toThrow("windy.modules.json Module package 无效：system");
+    }
+  });
+
+  test("状态、顺序和 config 必须满足结构约束", () => {
+    expect(() =>
+      validateProjectModuleAssembly({
+        ...validAssembly,
+        modules: [{ ...validAssembly.modules[0], enabled: "yes" }],
+      }),
+    ).toThrow("windy.modules.json Module enabled 无效：system");
+    expect(() =>
+      validateProjectModuleAssembly({
+        ...validAssembly,
+        modules: [
+          {
+            ...validAssembly.modules[0],
+            admin: { visible: 1 },
+          },
+        ],
+      }),
+    ).toThrow("windy.modules.json Module admin.visible 无效：system");
+
+    for (const order of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+      expect(() =>
+        validateProjectModuleAssembly({
+          ...validAssembly,
+          modules: [{ ...validAssembly.modules[0], order }],
+        }),
+      ).toThrow("windy.modules.json Module order 无效：system");
+    }
+
+    for (const config of [null, [], new Date(), "配置"]) {
+      expect(() =>
+        validateProjectModuleAssembly({
+          ...validAssembly,
+          modules: [{ ...validAssembly.modules[0], config }],
+        }),
+      ).toThrow("windy.modules.json Module config 无效：system");
+    }
+  });
+
+  test("order 重复时拒绝，避免装配顺序不确定", () => {
+    expect(() =>
+      validateProjectModuleAssembly({
+        ...validAssembly,
+        modules: [
+          validAssembly.modules[0],
+          { ...validAssembly.modules[1], order: 100 },
+        ],
+      }),
+    ).toThrow("windy.modules.json Module order 重复：100");
+  });
+});

package/template/packages/modules/src/project-module-assembly.ts

@@ -0,0 +1,126 @@
+export interface ProjectModuleAdminSettings {
+  readonly visible: boolean;
+}
+
+export interface ProjectModuleRegistration {
+  readonly name: string;
+  readonly package: string | null;
+  readonly enabled: boolean;
+  readonly order: number;
+  readonly admin: ProjectModuleAdminSettings;
+  readonly config: Readonly<Record<string, unknown>>;
+}
+
+export interface ProjectModuleAssembly {
+  readonly schemaVersion: 1;
+  readonly modules: readonly ProjectModuleRegistration[];
+}
+
+export function validateProjectModuleAssembly(
+  value: unknown,
+): ProjectModuleAssembly {
+  if (!isPlainObject(value)) {
+    throw new Error("windy.modules.json 必须是对象");
+  }
+  if (value.schemaVersion !== 1) {
+    throw new Error(
+      `windy.modules.json schemaVersion 不受支持：${String(value.schemaVersion)}`,
+    );
+  }
+  if (!Array.isArray(value.modules)) {
+    throw new Error("windy.modules.json modules 必须是数组");
+  }
+
+  const names = new Set<string>();
+  const orders = new Set<number>();
+  const modules = value.modules.map((entry) => {
+    const registration = validateRegistration(entry);
+    if (names.has(registration.name)) {
+      throw new Error(`windy.modules.json Module 重复：${registration.name}`);
+    }
+    if (orders.has(registration.order)) {
+      throw new Error(
+        `windy.modules.json Module order 重复：${registration.order}`,
+      );
+    }
+    names.add(registration.name);
+    orders.add(registration.order);
+    return registration;
+  });
+
+  return { schemaVersion: 1, modules };
+}
+
+export function indexProjectModuleAssembly(
+  assembly: ProjectModuleAssembly,
+): ReadonlyMap<string, ProjectModuleRegistration> {
+  const validated = validateProjectModuleAssembly(assembly);
+  return new Map(validated.modules.map((entry) => [entry.name, entry]));
+}
+
+function validateRegistration(value: unknown): ProjectModuleRegistration {
+  if (!isPlainObject(value)) {
+    throw new Error("windy.modules.json Module 必须是对象");
+  }
+  if (typeof value.name !== "string" || !value.name.trim()) {
+    throw new Error("windy.modules.json Module 名称不能为空");
+  }
+  const name = value.name;
+  if (
+    value.package !== null &&
+    (typeof value.package !== "string" || !isValidNpmPackageName(value.package))
+  ) {
+    throw new Error(`windy.modules.json Module package 无效：${name}`);
+  }
+  if (typeof value.enabled !== "boolean") {
+    throw new Error(`windy.modules.json Module enabled 无效：${name}`);
+  }
+  if (!isPlainObject(value.admin) || typeof value.admin.visible !== "boolean") {
+    throw new Error(`windy.modules.json Module admin.visible 无效：${name}`);
+  }
+  if (!Number.isSafeInteger(value.order) || Number(value.order) < 0) {
+    throw new Error(`windy.modules.json Module order 无效：${name}`);
+  }
+  if (!isPlainObject(value.config)) {
+    throw new Error(`windy.modules.json Module config 无效：${name}`);
+  }
+
+  return {
+    name,
+    package: value.package,
+    enabled: value.enabled,
+    order: Number(value.order),
+    admin: { visible: value.admin.visible },
+    config: value.config,
+  };
+}
+
+function isValidNpmPackageName(value: string): boolean {
+  if (!value || value.length > 214 || value !== value.toLowerCase()) {
+    return false;
+  }
+  const parts = value.startsWith("@") ? value.slice(1).split("/") : [value];
+  if (parts.length !== (value.startsWith("@") ? 2 : 1)) return false;
+  return parts.every(isValidNpmPackageNamePart);
+}
+
+function isValidNpmPackageNamePart(value: string): boolean {
+  if (
+    !value ||
+    value === "node_modules" ||
+    value === "favicon.ico" ||
+    value.startsWith(".") ||
+    value.startsWith("_")
+  ) {
+    return false;
+  }
+  return /^[a-z0-9!~*'()._-]+$/.test(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}

package/template/packages/modules/src/system-admin-routes.ts

@@ -15,7 +15,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "用户体系",
     "sidebar",
     "system.user.read",
-    "system.rbac",
+    "system.user",
   ),
   route(
     "system.role",
@@ -23,7 +23,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "权限策略",
     "sidebar",
     "system.role.read",
-    "system.rbac",
+    "system.role",
   ),
   route(
     "system.department",
@@ -31,7 +31,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "部门组织",
     "sidebar",
     "system.department.read",
-    "system.rbac",
+    "system.department",
   ),
   // @windy-module system.settings begin
   {
@@ -52,7 +52,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "菜单管理",
     "sidebar",
     "system.menu.read",
-    "system.rbac",
+    "system.menu",
   ),
   route(
     "system.dictionary",
@@ -60,7 +60,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "字典管理",
     "sidebar",
     "system.dict.read",
-    "system.rbac",
+    "system.dict",
   ),
   route(
     "system.feature",
@@ -68,6 +68,7 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "功能开关",
     "sidebar",
     "system.feature.read",
+    "system.feature",
   ),
   // @windy-module system.notification begin
   route(

package/template/packages/modules/src/system-admin-ui-catalog.ts

@@ -0,0 +1,72 @@
+import type { AdminUiManifest } from "./admin-ui-manifest.js";
+import { systemAdminRoutes } from "./system-admin-routes.js";
+
+const definitions = [
+  ["system", ["system.feature"]],
+  [
+    "system.identity",
+    [
+      "system.profile",
+      "system.user",
+      "system.role",
+      "system.department",
+      "system.menu",
+      "system.dictionary",
+    ],
+  ],
+  // @windy-module system.settings begin
+  ["system.settings", ["system.settings"]],
+  // @windy-module system.settings end
+  // @windy-module system.configuration begin
+  ["system.configuration", ["system.config"]],
+  // @windy-module system.configuration end
+  // @windy-module system.license begin
+  ["system.license", ["system.license"]],
+  // @windy-module system.license end
+  // @windy-module system.audit begin
+  ["system.audit", ["system.audit"]],
+  // @windy-module system.audit end
+  // @windy-module system.storage begin
+  ["system.storage", []],
+  // @windy-module system.storage end
+  // @windy-module system.agent begin
+  ["system.agent", []],
+  // @windy-module system.agent end
+  // @windy-module system.operations begin
+  ["system.operations", ["system.ops"]],
+  // @windy-module system.operations end
+  // @windy-module system.scheduler begin
+  ["system.scheduler", []],
+  // @windy-module system.scheduler end
+  // @windy-module system.notification begin
+  ["system.notification", ["system.notification"]],
+  // @windy-module system.notification end
+  // @windy-module system.workflow begin
+  ["system.workflow", []],
+  // @windy-module system.workflow end
+  // @windy-module system.bulk-data begin
+  ["system.bulk-data", []],
+  // @windy-module system.bulk-data end
+  // @windy-module system.search begin
+  ["system.search", []],
+  // @windy-module system.search end
+  // @windy-module system.data-governance begin
+  ["system.data-governance", []],
+  // @windy-module system.data-governance end
+] as const;
+
+const routeByKey = new Map(
+  systemAdminRoutes.map((route) => [route.key, route] as const),
+);
+
+export function systemAdminUiManifests(): AdminUiManifest[] {
+  return definitions.map(([name, routeKeys]) => ({
+    name,
+    version: "0.1.0",
+    adminRoutes: routeKeys.map((key) => {
+      const route = routeByKey.get(key);
+      if (!route) throw new Error(`系统 Admin Route 未定义：${key}`);
+      return { ...route };
+    }),
+  }));
+}

package/template/packages/modules/src/system-agent-tools.ts

@@ -55,7 +55,7 @@ export const systemAgentTools: ModuleManifest["tools"] = [
     label: "查询用户",
     description: "分页查询平台用户账号。",
     permissionKey: "system.user.read",
-    featureKey: "system.rbac",
+    featureKey: "system.user",
     auditAction: "agent.tool.execute",
     scopeMode: "request",
   },
@@ -65,7 +65,7 @@ export const systemAgentTools: ModuleManifest["tools"] = [
     label: "查询功能开关",
     description: "分页查询平台功能开关状态。",
     permissionKey: "system.feature.read",
-    featureKey: "system.rbac",
+    featureKey: "system.feature",
     auditAction: "agent.tool.execute",
   },
   {