sy-lowcode-workspace-tools 0.1.0

package/scripts/utils/mime-types.mjs

@@ -0,0 +1,70 @@
+/**
+ * mime-types.mjs - MIME 类型映射
+ *
+ * 提供文件扩展名到 MIME 类型的映射，支持 JS/CSS/JSON/HTML、
+ * 图片、字体和其他常见静态资源类型。
+ */
+
+import path from "node:path";
+
+/** @type {Record<string, string>} 扩展名 → MIME 类型映射表 */
+const MIME_MAP = {
+  // 脚本 & 样式
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".html": "text/html",
+  // 图片
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".avif": "image/avif",
+  // 字体
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".eot": "application/vnd.ms-fontobject",
+  // 其他
+  ".map": "application/json",
+};
+
+/**
+ * 根据文件路径获取对应的 MIME 类型
+ * @param {string} file - 文件路径
+ * @returns {string} MIME 类型
+ */
+export function getContentType(file) {
+  const ext = path.extname(file).toLowerCase();
+  return MIME_MAP[ext] || "application/octet-stream";
+}
+
+/**
+ * 判断文件名是否包含 content hash（如 logo-abc123.png）
+ * 匹配模式：name-[8+位hex hash].ext
+ * @param {string} file - 文件名或路径
+ * @returns {boolean}
+ */
+export function hasContentHash(file) {
+  const basename = path.basename(file);
+  return /\-[a-f0-9]{8,}\.[^.]+$/.test(basename);
+}
+
+/**
+ * 根据文件特征返回合适的 Cache-Control 头
+ * - 带 content hash 的资源 → 长期缓存 + immutable
+ * - 其他文件 → 长期缓存（依赖 buildId 路径做版本隔离）
+ * @param {string} file - 文件路径
+ * @returns {string} Cache-Control 头值
+ */
+export function getCacheControl(file) {
+  if (hasContentHash(file)) {
+    return "public, max-age=31536000, immutable";
+  }
+  // 入口文件依赖 buildId 路径做版本隔离，同样可以长期缓存
+  return "public, max-age=31536000";
+}

package/scripts/utils/oss-client.mjs

@@ -0,0 +1,128 @@
+/**
+ * oss-client.mjs - 阿里云 OSS 客户端工具
+ *
+ * 封装 OSS 客户端初始化、带重试的上传、以及 CORS 规则确保。
+ */
+
+import OSS from "ali-oss";
+
+/**
+ * 创建阿里云 OSS 客户端实例
+ * @param {object} ossConfig - OSS 配置
+ * @param {string} ossConfig.region - OSS Region
+ * @param {string} ossConfig.bucket - Bucket 名称
+ * @param {string} ossConfig.accessKeyId - AccessKey ID
+ * @param {string} ossConfig.accessKeySecret - AccessKey Secret
+ * @returns {import("ali-oss")} OSS 客户端实例
+ */
+export function createOSSClient(ossConfig) {
+  return new OSS({
+    region: ossConfig.region,
+    accessKeyId: ossConfig.accessKeyId,
+    accessKeySecret: ossConfig.accessKeySecret,
+    bucket: ossConfig.bucket,
+  });
+}
+
+/**
+ * 带重试机制的 OSS 上传
+ * @param {import("ali-oss")} client - OSS 客户端实例
+ * @param {string} ossKey - OSS 对象键
+ * @param {string} localPath - 本地文件路径
+ * @param {object} headers - HTTP 头（Cache-Control, Content-Type 等）
+ * @param {number} [retries=3] - 最大重试次数
+ * @returns {Promise<void>}
+ */
+export async function uploadWithRetry(client, ossKey, localPath, headers, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await client.put(ossKey, localPath, { headers });
+      return;
+    } catch (err) {
+      if (i === retries - 1) throw err;
+      console.warn(`  ⚠ 重试 ${i + 1}/${retries}: ${ossKey}`);
+      await new Promise((r) => setTimeout(r, 1000 * (i + 1)));
+    }
+  }
+}
+
+/**
+ * @param {*} value
+ * @returns {string[]}
+ */
+function toArray(value) {
+  if (Array.isArray(value)) return value;
+  if (value === undefined || value === null || value === "") return [];
+  return [value];
+}
+
+/**
+ * 检查单条 CORS 规则是否已满足指定 origins 和 methods
+ * @param {object} rule - CORS 规则对象
+ * @param {string[]} origins - 需要允许的来源
+ * @param {string[]} methods - 需要允许的方法
+ * @returns {boolean}
+ */
+function corsRuleAllows(rule, origins, methods) {
+  const allowedOrigins = toArray(rule.allowedOrigin);
+  const allowedMethods = toArray(rule.allowedMethod).map((item) =>
+    String(item).toUpperCase(),
+  );
+
+  const originAllowed =
+    allowedOrigins.includes("*") ||
+    origins.every((origin) => allowedOrigins.includes(origin));
+  const methodAllowed = methods.every((method) =>
+    allowedMethods.includes(method),
+  );
+
+  return originAllowed && methodAllowed;
+}
+
+/**
+ * 确保 OSS Bucket 的 CORS 规则满足前端资源加载需求
+ * @param {import("ali-oss")} client - OSS 客户端实例
+ * @param {object} ossConfig - OSS 配置
+ * @param {string} ossConfig.bucket - Bucket 名称
+ * @param {boolean} [ossConfig.skipCors] - 是否跳过 CORS 检查
+ * @param {string[]} [ossConfig.corsOrigins] - 允许的来源列表
+ * @returns {Promise<void>}
+ */
+export async function ensureBucketCors(client, ossConfig) {
+  if (ossConfig.skipCors) {
+    console.log("   CORS: 跳过（APP_OSS_SKIP_CORS=1）");
+    return;
+  }
+
+  const origins = ossConfig.corsOrigins?.length
+    ? ossConfig.corsOrigins
+    : ["*"];
+  const methods = ["GET", "HEAD"];
+  let rules = [];
+
+  try {
+    const result = await client.getBucketCORS(ossConfig.bucket);
+    rules = Array.isArray(result.rules) ? result.rules : [];
+  } catch (error) {
+    if (error?.status !== 404 && error?.code !== "NoSuchCORSConfiguration") {
+      throw error;
+    }
+  }
+
+  if (rules.some((rule) => corsRuleAllows(rule, origins, methods))) {
+    console.log(`   CORS: 已允许 ${origins.join(", ")}`);
+    return;
+  }
+
+  await client.putBucketCORS(ossConfig.bucket, [
+    ...rules,
+    {
+      allowedOrigin: origins,
+      allowedMethod: methods,
+      allowedHeader: "*",
+      exposeHeader: ["ETag", "Content-Length", "Content-Type"],
+      maxAgeSeconds: "3600",
+    },
+  ]);
+  console.log(`   CORS: 已配置 ${origins.join(", ")}`);
+}

package/scripts/utils/pages.mjs

@@ -0,0 +1,80 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { rootDir as workspaceRoot } from "./load-config.mjs";
+
+export const rootDir = workspaceRoot;
+export const srcRoot = path.join(rootDir, "src");
+export const formsRoot = path.join(srcRoot, "forms");
+export const pagesRoot = path.join(srcRoot, "pages");
+export const distRoot = path.join(rootDir, "dist");
+
+async function fileExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadTypeScriptModule(filePath) {
+  const loaded = await import(pathToFileURL(filePath).href);
+  return loaded.default || loaded;
+}
+
+export async function discoverPages(filterName = "") {
+  if (!(await fileExists(pagesRoot))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(pagesRoot, { withFileTypes: true });
+  const pages = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (filterName && entry.name !== filterName) continue;
+
+    const dirPath = path.join(pagesRoot, entry.name);
+    const entryPath = path.join(dirPath, "index.tsx");
+    const appPath = path.join(dirPath, "App.tsx");
+    const configPath = path.join(dirPath, "page.config.ts");
+    const required = [entryPath, appPath, configPath];
+    const exists = await Promise.all(required.map(fileExists));
+    if (exists.every((item) => !item)) continue;
+    for (let index = 0; index < required.length; index += 1) {
+      if (!exists[index]) {
+        throw new Error(`页面 ${entry.name} 缺少文件: ${path.basename(required[index])}`);
+      }
+    }
+
+    const config = await loadTypeScriptModule(configPath);
+    if (config.publish === false) continue;
+    pages.push({
+      dirName: entry.name,
+      dirPath,
+      entryPath,
+      appPath,
+      configPath,
+      config,
+    });
+  }
+
+  return pages.sort((left, right) =>
+    String(left.config.name || left.dirName).localeCompare(
+      String(right.config.name || right.dirName),
+      "zh-Hans-CN",
+    ),
+  );
+}
+
+export async function readPackageJson() {
+  return JSON.parse(await fs.readFile(path.join(rootDir, "package.json"), "utf8"));
+}
+
+export async function getReactVersion() {
+  const packageJson = await readPackageJson();
+  return String(packageJson.dependencies?.react || "")
+    .replace(/^[~^]/, "")
+    .trim();
+}

package/scripts/utils/progress.mjs

@@ -0,0 +1,57 @@
+/**
+ * progress.mjs - 上传进度报告工具
+ *
+ * 提供文件上传进度跟踪，包括已完成数量、文件总大小、耗时统计。
+ */
+
+import fs from "node:fs";
+
+/**
+ * 创建进度跟踪器
+ * @param {number} total - 总文件数
+ * @returns {{ tick: (file: string, localPath: string) => void, summary: () => void }}
+ */
+export function createProgressTracker(total) {
+  let completed = 0;
+  let totalBytes = 0;
+  const startTime = Date.now();
+
+  return {
+    /**
+     * 标记一个文件上传完成
+     * @param {string} ossKey - OSS 对象键（用于日志）
+     * @param {string} localPath - 本地文件路径（用于计算大小）
+     */
+    tick(ossKey, localPath) {
+      completed += 1;
+      try {
+        const stat = fs.statSync(localPath);
+        totalBytes += stat.size;
+      } catch {
+        // 忽略 stat 失败
+      }
+      const pct = Math.round((completed / total) * 100);
+      console.log(`  ✓ [${completed}/${total} ${pct}%] ${ossKey}`);
+    },
+
+    /**
+     * 标记一个文件上传失败
+     * @param {string} ossKey - OSS 对象键
+     * @param {Error} error - 错误对象
+     */
+    fail(ossKey, error) {
+      completed += 1;
+      const pct = Math.round((completed / total) * 100);
+      console.error(`  ✗ [${completed}/${total} ${pct}%] ${ossKey}: ${error.message}`);
+    },
+
+    /**
+     * 打印上传汇总信息
+     */
+    summary() {
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      const sizeMB = (totalBytes / (1024 * 1024)).toFixed(2);
+      console.log(`\n📊 上传统计: ${total} 个文件, ${sizeMB} MB, 耗时 ${elapsed}s`);
+    },
+  };
+}

package/scripts/utils/register-payload.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getPageAssetBaseUrl,
+  getPageAssetUrl,
+  getPageRuntimeUrl,
+  rootDir,
+} from "./load-config.mjs";
+
+function readPageRuntimeManifest() {
+  const manifestPath = path.resolve(rootDir, "dist/page-runtime/manifest.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    if (
+      manifest?.protocol !== "sy-page-runtime" ||
+      manifest?.majorVersion !== 1 ||
+      !manifest?.version ||
+      !manifest?.files?.entry
+    ) {
+      return null;
+    }
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+export function buildPageMenuConfig(config, pageConfig) {
+  if (pageConfig.menu?.enabled === false) {
+    return { enabled: false };
+  }
+
+  return {
+    enabled: true,
+    name: pageConfig.menu?.name || pageConfig.name,
+    parentId:
+      pageConfig.menu && "parentId" in pageConfig.menu
+        ? pageConfig.menu.parentId
+        : config.defaults.pageMenuParentId || null,
+    icon:
+      pageConfig.menu && "icon" in pageConfig.menu
+        ? pageConfig.menu.icon
+        : config.defaults.pageMenuIcon || null,
+  };
+}
+
+export function buildDirectPagePublishPayload(config, pages) {
+  const pageRuntime = readPageRuntimeManifest();
+  return {
+    appType: config.appType,
+    userId: config.userId,
+    version: config.version,
+    buildId: config.buildId,
+    pages: pages.map((page) => {
+      const pageBaseUrl = getPageAssetBaseUrl(config, page.config.code);
+      const pageEntryUrl = getPageAssetUrl(config, page.config.code, "index.js");
+      const pageStyleUrl = getPageAssetUrl(config, page.config.code, "style.css");
+      const runtimeJsUrl = pageRuntime?.files?.entry
+        ? getPageRuntimeUrl(config, pageRuntime.files.entry)
+        : null;
+      const runtimeCssUrl = pageRuntime?.files?.css
+        ? getPageRuntimeUrl(config, pageRuntime.files.css)
+        : null;
+      return {
+        code: page.config.code,
+        name: page.config.name,
+        description: page.config.description || "",
+        route: page.config.route,
+        props: page.config.props || {},
+        dataSources: page.config.dataSources || [],
+        runtime: {
+          entryUrl: pageEntryUrl,
+          cssUrls: [runtimeCssUrl, pageStyleUrl].filter(Boolean),
+          jsUrls: runtimeJsUrl ? [runtimeJsUrl] : [pageEntryUrl],
+          cdnBaseUrl: pageBaseUrl,
+          framework: "react",
+          frameworkVersion: config.defaults.frameworkVersion,
+          protocolVersion: config.defaults.protocolVersion,
+          protocol: pageRuntime?.protocol || undefined,
+          version: config.version,
+          cssIsolation:
+            page.config.cssIsolation || config.defaults.cssIsolation,
+        },
+        menu: buildPageMenuConfig(config, page.config),
+      };
+    }),
+  };
+}

package/scripts/utils/register-payload.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+
+import { getFormBundleUrl, getPageAssetUrl } from "./load-config.mjs";
+import { discoverPages } from "./pages.mjs";
+import { buildDirectPagePublishPayload } from "./register-payload.mjs";
+
+const config = {
+  appType: "APP_TEST",
+  userId: "user-1",
+  version: "1.2.3",
+  buildId: "BUILD_001",
+  oss: {
+    bucket: "bucket",
+    region: "oss-cn-hangzhou",
+    pathPrefix: "lowcode/app-workspace/dev",
+  },
+  defaults: {
+    frameworkVersion: "19.0.0",
+    protocolVersion: "1.0",
+    cssIsolation: "shadow",
+    pageMenuParentId: "MENU_PARENT",
+    pageMenuIcon: "dashboard",
+  },
+};
+
+describe("register payload helpers", () => {
+  it("discovers publishable code pages", async () => {
+    const pages = await discoverPages("customer-dashboard");
+
+    expect(pages).toHaveLength(1);
+    expect(pages[0].config.code).toBe("customer-dashboard");
+  });
+
+  it("builds stable form and page asset URLs from one build id", () => {
+    expect(getFormBundleUrl(config, "customer-info", "index.js")).toBe(
+      "https://bucket.oss-cn-hangzhou.aliyuncs.com/lowcode/app-workspace/dev/1.2.3/BUILD_001/forms/customer-info/index.js",
+    );
+    expect(getPageAssetUrl(config, "customer-dashboard", "style.css")).toBe(
+      "https://bucket.oss-cn-hangzhou.aliyuncs.com/lowcode/app-workspace/dev/1.2.3/BUILD_001/pages/customer-dashboard/style.css",
+    );
+  });
+
+  it("builds direct custom page payloads without manifest fields", () => {
+    const payload = buildDirectPagePublishPayload(config, [
+      {
+        config: {
+          code: "customer-dashboard",
+          name: "客户经营看板",
+          route: { pathKey: "customer-dashboard" },
+          props: { title: "客户经营看板" },
+          dataSources: [],
+        },
+      },
+    ]);
+
+    expect(payload.pages[0].runtime.entryUrl).toBe(
+      "https://bucket.oss-cn-hangzhou.aliyuncs.com/lowcode/app-workspace/dev/1.2.3/BUILD_001/pages/customer-dashboard/index.js",
+    );
+    expect(JSON.stringify(payload)).not.toMatch(/manifest/i);
+  });
+
+  it("marks menu disabled pages so the backend skips menu upsert", () => {
+    const payload = buildDirectPagePublishPayload(config, [
+      {
+        config: {
+          code: "internal-dashboard",
+          name: "内部看板",
+          route: { pathKey: "internal-dashboard" },
+          menu: { enabled: false },
+        },
+      },
+    ]);
+
+    expect(payload.pages[0].menu).toEqual({ enabled: false });
+  });
+});

package/scripts/utils/schema-transform.mjs

@@ -0,0 +1,130 @@
+export function normalizeComponentName(componentName) {
+  if (componentName === "TextAreaField") return "TextareaField";
+  return componentName;
+}
+
+export function getObjectSize(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return 0;
+  return Object.keys(value).length;
+}
+
+export function isValidTableName(value) {
+  const normalized = String(value || "").trim();
+  return Boolean(normalized) && normalized.toLowerCase() !== "null";
+}
+
+export function validateFormSchema(schema, formName = "unknown") {
+  if (!schema || typeof schema !== "object") {
+    throw new Error(`${formName}: schema 必须是对象`);
+  }
+  if (!schema.formMeta || typeof schema.formMeta !== "object") {
+    throw new Error(`${formName}: schema.formMeta 缺失`);
+  }
+  if (!Array.isArray(schema.fields) || schema.fields.length === 0) {
+    throw new Error(`${formName}: schema.fields 不能为空`);
+  }
+
+  const seenFieldIds = new Set();
+  schema.fields.forEach((field, index) => {
+    const fieldLabel = `${formName}: fields[${index}]`;
+    if (!field || typeof field !== "object") {
+      throw new Error(`${fieldLabel} 必须是对象`);
+    }
+    const fieldId = String(field.fieldId || "").trim();
+    if (!fieldId) {
+      throw new Error(`${fieldLabel}.fieldId 不能为空`);
+    }
+    if (seenFieldIds.has(fieldId)) {
+      throw new Error(`${formName}: fieldId 重复: ${fieldId}`);
+    }
+    seenFieldIds.add(fieldId);
+    if (!String(field.componentName || "").trim()) {
+      throw new Error(`${fieldLabel}.componentName 不能为空`);
+    }
+  });
+}
+
+export function createFormComponentNode(field, index) {
+  const componentName = normalizeComponentName(field.componentName);
+
+  return {
+    componentName,
+    id: field.id || `${field.fieldId || componentName}_${index + 1}`,
+    title: field.label || field.fieldId || componentName,
+    hidden: false,
+    isLocked: false,
+    condition: true,
+    conditionGroup: "",
+    props: {
+      ...field,
+      componentName,
+      isFormComponent: true,
+      fieldId: field.fieldId,
+      label: field.label || field.fieldId,
+      tips: field.tips || "",
+      value: field.value || "",
+      placeholder: field.placeholder || "",
+    },
+  };
+}
+
+export function transformToApiFormat(schema, formName = "unknown") {
+  validateFormSchema(schema, formName);
+
+  const { formMeta, fields } = schema;
+  const componentNodes = fields.map(createFormComponentNode);
+  const pageSchema = {
+    version: "2.0",
+    componentsTree: [
+      {
+        componentName: "Page",
+        id: `${formMeta.formUuid || "form"}_page`,
+        props: {},
+        children: componentNodes,
+      },
+    ],
+  };
+
+  return {
+    formUuid: formMeta.formUuid,
+    appType: formMeta.appType,
+    fieldCount: componentNodes.length,
+    schema: JSON.stringify(pageSchema),
+    packages: JSON.stringify({}),
+  };
+}
+
+export function assertSchemaSyncResult(body, expectedFieldCount) {
+  if (body?.code !== 200) {
+    throw new Error(
+      `API 业务失败: ${body?.code || "unknown"} ${body?.message || ""}`,
+    );
+  }
+
+  if (!isValidTableName(body?.data?.tableName)) {
+    throw new Error("API 同步后未返回有效 tableName，表结构可能未创建");
+  }
+
+  const actualFieldCount = getObjectSize(body?.data?.formFields);
+  if (actualFieldCount !== expectedFieldCount) {
+    throw new Error(
+      `API 同步后 formFields 数量不匹配，期望 ${expectedFieldCount}，实际 ${actualFieldCount}`,
+    );
+  }
+}
+
+export function assertFormReadyForBundle(formMeta, formName = "unknown") {
+  if (!formMeta) {
+    throw new Error(`${formName}: 平台未找到表单定义`);
+  }
+  if (!isValidTableName(formMeta.tableName)) {
+    throw new Error(
+      `${formName}: 平台表单缺少 tableName，请先运行 pnpm sync-schema --form ${formName}`,
+    );
+  }
+  if (getObjectSize(formMeta.formFields) === 0) {
+    throw new Error(
+      `${formName}: 平台表单缺少 formFields，请先运行 pnpm sync-schema --form ${formName}`,
+    );
+  }
+}