@lark-apaas/coding-html-devserver 0.1.1 → 0.1.2

package/lib/build.d.ts

@@ -11,6 +11,8 @@ export interface BuildResult {
     readonly outDir: string;
     /** 注入（并按需压缩）过的 html 产物绝对路径列表。 */
     readonly htmlFiles: string[];
+    /** routes.json 产物绝对路径（源里有则透传、没有则补默认）。 */
+    readonly routesJson: string;
 }
 /**
  * build：把 `root` 全量**纯拷贝**到 `outDir`（文件名/路径/结构逐字保留），
@@ -18,5 +20,9 @@ export interface BuildResult {
  *
  * 不走 vite build —— 不打包、不加 hash、不改写路径，保证「产物 = 源码」。
  * 注入与 dev 共用 `injectPlatformTags`，两条路一致。
+ *
+ * routes.json（平台路由清单）：纯拷贝已把源里手维护的带出来（透传）；若源没有，则扫描
+ * `root` 下的 `*.html` 生成 `[{path}]`，**带上 `CLIENT_BASE_PATH` 前缀**（build 场景）。
+ * MPA 由物理 .html 直出，routes.json 列出页面路由。
  */
 export declare function buildStatic(opts?: BuildOptions): Promise<BuildResult>;

package/lib/build.js

@@ -8,6 +8,8 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const transform_1 = require("./transform");
 const minify_1 = require("./minify");
+const routes_1 = require("./routes");
+const normalize_base_path_1 = require("./normalize-base-path");
 const HTML_EXT = new Set(['.html', '.htm']);
 /**
  * build：把 `root` 全量**纯拷贝**到 `outDir`（文件名/路径/结构逐字保留），
@@ -15,6 +17,10 @@ const HTML_EXT = new Set(['.html', '.htm']);
  *
  * 不走 vite build —— 不打包、不加 hash、不改写路径，保证「产物 = 源码」。
  * 注入与 dev 共用 `injectPlatformTags`，两条路一致。
+ *
+ * routes.json（平台路由清单）：纯拷贝已把源里手维护的带出来（透传）；若源没有，则扫描
+ * `root` 下的 `*.html` 生成 `[{path}]`，**带上 `CLIENT_BASE_PATH` 前缀**（build 场景）。
+ * MPA 由物理 .html 直出，routes.json 列出页面路由。
  */
 async function buildStatic(opts = {}) {
     const root = node_path_1.default.resolve(opts.root ?? 'src');
@@ -36,7 +42,14 @@ async function buildStatic(opts = {}) {
         await node_fs_1.default.promises.writeFile(file, html, 'utf8');
         htmlFiles.push(file);
     }
-    return { root, outDir, htmlFiles };
+    // 源根有 routes.json → 纯拷贝已带出（透传手维护版）；没有 → 扫描生成（带 CLIENT_BASE_PATH 前缀）
+    const routesJson = node_path_1.default.join(outDir, routes_1.ROUTES_JSON_FILENAME);
+    if (!node_fs_1.default.existsSync(routesJson)) {
+        const basePath = (0, normalize_base_path_1.normalizeBasePath)(process.env.CLIENT_BASE_PATH);
+        const routes = (0, routes_1.generateRoutes)(root, basePath);
+        await node_fs_1.default.promises.writeFile(routesJson, JSON.stringify(routes, null, 2) + '\n', 'utf8');
+    }
+    return { root, outDir, htmlFiles, routesJson };
 }
 function* walk(dir) {
     for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {

package/lib/index.d.ts

@@ -4,6 +4,9 @@ export type { HtmlViteOptions } from './vite-config';
 export { buildStatic } from './build';
 export type { BuildOptions, BuildResult } from './build';
 export { minifyHtmlWithHbsProtection } from './minify';
+export { generateRoutes, resolveRoutesJson, routePathFromFile, ROUTES_JSON_FILENAME, } from './routes';
+export type { RouteEntry } from './routes';
+export { normalizeBasePath } from './normalize-base-path';
 export { injectPlatformTags, PLATFORM_TAGS } from './transform';
 export type { InjectPlatformOptions } from './transform';
 export { viewContextTag, buildRenderContext } from './transform/view-context';
@@ -22,3 +25,5 @@ export { viteClientPatchPlugin } from './plugins/vite-client-patch';
 export { wsWatchdogPlugin } from './plugins/ws-watchdog';
 export type { WsWatchdogPluginOptions } from './plugins/ws-watchdog';
 export { basePathRewritePlugin } from './plugins/base-path';
+export { routesJsonPlugin } from './plugins/routes-json';
+export type { RoutesJsonPluginOptions } from './plugins/routes-json';

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.basePathRewritePlugin = exports.wsWatchdogPlugin = exports.viteClientPatchPlugin = exports.platformInjectPlugin = exports.HEALTH_ENDPOINT = exports.healthPlugin = exports.serializeTag = exports.injectTags = exports.injectOgMeta = exports.MIAODA_PREVIEW_BRIDGE_URL = exports.previewBridgeTags = exports.slardarTags = exports.buildRenderContext = exports.viewContextTag = exports.PLATFORM_TAGS = exports.injectPlatformTags = exports.minifyHtmlWithHbsProtection = exports.buildStatic = exports.createHtmlViteConfig = exports.startDevServer = void 0;
+exports.routesJsonPlugin = exports.basePathRewritePlugin = exports.wsWatchdogPlugin = exports.viteClientPatchPlugin = exports.platformInjectPlugin = exports.HEALTH_ENDPOINT = exports.healthPlugin = exports.serializeTag = exports.injectTags = exports.injectOgMeta = exports.MIAODA_PREVIEW_BRIDGE_URL = exports.previewBridgeTags = exports.slardarTags = exports.buildRenderContext = exports.viewContextTag = exports.PLATFORM_TAGS = exports.injectPlatformTags = exports.normalizeBasePath = exports.ROUTES_JSON_FILENAME = exports.routePathFromFile = exports.resolveRoutesJson = exports.generateRoutes = exports.minifyHtmlWithHbsProtection = exports.buildStatic = exports.createHtmlViteConfig = exports.startDevServer = void 0;
 var dev_1 = require("./dev");
 Object.defineProperty(exports, "startDevServer", { enumerable: true, get: function () { return dev_1.startDevServer; } });
 var vite_config_1 = require("./vite-config");
@@ -9,6 +9,13 @@ var build_1 = require("./build");
 Object.defineProperty(exports, "buildStatic", { enumerable: true, get: function () { return build_1.buildStatic; } });
 var minify_1 = require("./minify");
 Object.defineProperty(exports, "minifyHtmlWithHbsProtection", { enumerable: true, get: function () { return minify_1.minifyHtmlWithHbsProtection; } });
+var routes_1 = require("./routes");
+Object.defineProperty(exports, "generateRoutes", { enumerable: true, get: function () { return routes_1.generateRoutes; } });
+Object.defineProperty(exports, "resolveRoutesJson", { enumerable: true, get: function () { return routes_1.resolveRoutesJson; } });
+Object.defineProperty(exports, "routePathFromFile", { enumerable: true, get: function () { return routes_1.routePathFromFile; } });
+Object.defineProperty(exports, "ROUTES_JSON_FILENAME", { enumerable: true, get: function () { return routes_1.ROUTES_JSON_FILENAME; } });
+var normalize_base_path_1 = require("./normalize-base-path");
+Object.defineProperty(exports, "normalizeBasePath", { enumerable: true, get: function () { return normalize_base_path_1.normalizeBasePath; } });
 var transform_1 = require("./transform");
 Object.defineProperty(exports, "injectPlatformTags", { enumerable: true, get: function () { return transform_1.injectPlatformTags; } });
 Object.defineProperty(exports, "PLATFORM_TAGS", { enumerable: true, get: function () { return transform_1.PLATFORM_TAGS; } });
@@ -36,3 +43,5 @@ var ws_watchdog_1 = require("./plugins/ws-watchdog");
 Object.defineProperty(exports, "wsWatchdogPlugin", { enumerable: true, get: function () { return ws_watchdog_1.wsWatchdogPlugin; } });
 var base_path_1 = require("./plugins/base-path");
 Object.defineProperty(exports, "basePathRewritePlugin", { enumerable: true, get: function () { return base_path_1.basePathRewritePlugin; } });
+var routes_json_1 = require("./plugins/routes-json");
+Object.defineProperty(exports, "routesJsonPlugin", { enumerable: true, get: function () { return routes_json_1.routesJsonPlugin; } });

package/lib/normalize-base-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 标准化 base path（路径语义，强制 `/` 前缀、去尾斜杠）：
+ *   '' / undefined / '/' → ''；'foo' → '/foo'；'/app/x/' → '/app/x'。
+ * 语义对齐 `@lark-apaas/coding-preset-vite-react` 的 normalizeBasePath。
+ */
+export declare function normalizeBasePath(input: string | undefined): string;

package/lib/normalize-base-path.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBasePath = normalizeBasePath;
+/**
+ * 标准化 base path（路径语义，强制 `/` 前缀、去尾斜杠）：
+ *   '' / undefined / '/' → ''；'foo' → '/foo'；'/app/x/' → '/app/x'。
+ * 语义对齐 `@lark-apaas/coding-preset-vite-react` 的 normalizeBasePath。
+ */
+function normalizeBasePath(input) {
+    if (!input)
+        return '';
+    const p = input.trim();
+    if (!p || p === '/')
+        return '';
+    return (p.startsWith('/') ? p : '/' + p).replace(/\/+$/, '');
+}

package/lib/plugins/routes-json.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from 'vite';
+/**
+ * dev 期在 `${clientBasePath}/routes.json` 提供路由清单（与 build 一致）：源根有 routes.json
+ * 则透传，没有则扫描 `*.html` 生成 `[{path}]`。
+ *
+ * 路由 path **不带 base 前缀**（对齐 vite-react dev：base 由前缀消费方/网关处理；build 才带
+ * `CLIENT_BASE_PATH`）。显式 middleware 而非依赖 vite 静态托管：源无该文件时也能即时生成。
+ */
+export interface RoutesJsonPluginOptions {
+    /** dev server root（vite 已 resolve 的绝对路径）。 */
+    root: string;
+    /** 客户端 base path（如 `/app/app_xxx`）；空串退化到裸 `/routes.json`。 */
+    clientBasePath?: string;
+}
+export declare function routesJsonPlugin(options: RoutesJsonPluginOptions): Plugin;
+export default routesJsonPlugin;

package/lib/plugins/routes-json.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routesJsonPlugin = routesJsonPlugin;
+const routes_1 = require("../routes");
+function routesJsonPlugin(options) {
+    const { root, clientBasePath = '' } = options;
+    const urlPath = `${clientBasePath}/${routes_1.ROUTES_JSON_FILENAME}`;
+    return {
+        name: 'miaoda-html-routes-json',
+        apply: 'serve',
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const pathname = (req.url || '').split('?')[0];
+                if (pathname !== urlPath)
+                    return next();
+                res.setHeader('Content-Type', 'application/json');
+                res.setHeader('Cache-Control', 'no-cache');
+                res.end((0, routes_1.resolveRoutesJson)(root, ''));
+            });
+        },
+    };
+}
+exports.default = routesJsonPlugin;

package/lib/routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HTML 栈的路由清单 `routes.json`。
+ *
+ * 平台部署运行时（vefaas/沙箱网关）消费，格式对齐 `@lark-apaas/coding-preset-vite-react`
+ * 的 routesPlugin —— `[{ "path": "..." }]` 数组。vite-react 解析 `app.tsx` 的 `<Route>`；
+ * HTML 栈没有 Router，**扫描 root 下的 `*.html` 文件**，每个文件即一条路由（MPA）。
+ *
+ * 路径推导（与确认的规则一致）：
+ *   index.html        → /
+ *   about.html        → /about
+ *   about/index.html  → /about
+ *   foo/bar.html      → /foo/bar
+ * 再按 basePath 前缀（build 带 `CLIENT_BASE_PATH`，dev 空）。
+ *
+ * 源根已有手维护的 routes.json → 原样透传，不覆盖。
+ */
+export declare const ROUTES_JSON_FILENAME = "routes.json";
+export interface RouteEntry {
+    path: string;
+}
+/** 单个 .html 相对路径 → 路由 path（折叠 index、去扩展名、归一斜杠）。 */
+export declare function routePathFromFile(rel: string): string;
+/**
+ * 扫描 root 下的 `*.html` 生成路由列表，按 basePath 前缀。
+ * 无任何 html 时回退到单条根路由（对齐 vite-react 的 fallback）。
+ */
+export declare function generateRoutes(root: string, basePath?: string): RouteEntry[];
+/**
+ * 源根有 routes.json 则原样返回（手维护优先），否则扫描生成。dev 与 build 共用。
+ */
+export declare function resolveRoutesJson(root: string, basePath?: string): string;

package/lib/routes.js

@@ -0,0 +1,115 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTES_JSON_FILENAME = void 0;
+exports.routePathFromFile = routePathFromFile;
+exports.generateRoutes = generateRoutes;
+exports.resolveRoutesJson = resolveRoutesJson;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * HTML 栈的路由清单 `routes.json`。
+ *
+ * 平台部署运行时（vefaas/沙箱网关）消费，格式对齐 `@lark-apaas/coding-preset-vite-react`
+ * 的 routesPlugin —— `[{ "path": "..." }]` 数组。vite-react 解析 `app.tsx` 的 `<Route>`；
+ * HTML 栈没有 Router，**扫描 root 下的 `*.html` 文件**，每个文件即一条路由（MPA）。
+ *
+ * 路径推导（与确认的规则一致）：
+ *   index.html        → /
+ *   about.html        → /about
+ *   about/index.html  → /about
+ *   foo/bar.html      → /foo/bar
+ * 再按 basePath 前缀（build 带 `CLIENT_BASE_PATH`，dev 空）。
+ *
+ * 源根已有手维护的 routes.json → 原样透传，不覆盖。
+ */
+exports.ROUTES_JSON_FILENAME = 'routes.json';
+const HTML_EXT = /\.html?$/i;
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
+function* walkHtml(dir, base) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            yield* walkHtml(full, base);
+        }
+        else if (HTML_EXT.test(entry.name)) {
+            yield path.relative(base, full);
+        }
+    }
+}
+/** 单个 .html 相对路径 → 路由 path（折叠 index、去扩展名、归一斜杠）。 */
+function routePathFromFile(rel) {
+    const stripped = rel
+        .replace(/\\/g, '/') // win 分隔符归一
+        .replace(/\.html?$/i, '') // 去 .html/.htm
+        .replace(/(^|\/)index$/i, '$1'); // 折叠尾部 index
+    return '/' + stripped.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+/**
+ * 扫描 root 下的 `*.html` 生成路由列表，按 basePath 前缀。
+ * 无任何 html 时回退到单条根路由（对齐 vite-react 的 fallback）。
+ */
+function generateRoutes(root, basePath = '') {
+    const set = new Set();
+    for (const rel of walkHtml(root, root)) {
+        set.add(routePathFromFile(rel));
+    }
+    const paths = Array.from(set).sort();
+    const prefixed = paths.length > 0 ? paths.map((p) => (basePath ? basePath + p : p)) : [basePath ? `${basePath}/` : '/'];
+    return prefixed.map((p) => ({ path: p }));
+}
+/**
+ * 源根有 routes.json 则原样返回（手维护优先），否则扫描生成。dev 与 build 共用。
+ */
+function resolveRoutesJson(root, basePath = '') {
+    const p = path.join(root, exports.ROUTES_JSON_FILENAME);
+    try {
+        if (fs.existsSync(p))
+            return fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        /* 读失败退化到扫描生成 */
+    }
+    return JSON.stringify(generateRoutes(root, basePath), null, 2);
+}

package/lib/vite-config.js

@@ -10,19 +10,8 @@ const inject_1 = require("./plugins/inject");
 const vite_client_patch_1 = require("./plugins/vite-client-patch");
 const ws_watchdog_1 = require("./plugins/ws-watchdog");
 const base_path_1 = require("./plugins/base-path");
-/**
- * 标准化 base path（路径语义，强制 `/` 前缀、去尾斜杠）：
- *   '' / undefined / '/' → ''；'foo' → '/foo'；'/app/x/' → '/app/x'。
- * 语义对齐 `@lark-apaas/coding-preset-vite-react` 的 normalizeBasePath。
- */
-function normalizeBasePath(input) {
-    if (!input)
-        return '';
-    const p = input.trim();
-    if (!p || p === '/')
-        return '';
-    return (p.startsWith('/') ? p : '/' + p).replace(/\/+$/, '');
-}
+const routes_json_1 = require("./plugins/routes-json");
+const normalize_base_path_1 = require("./normalize-base-path");
 /**
  * html stack 的 vite dev 配置（仅 dev 用，build 不走 vite）。
  *
@@ -47,7 +36,7 @@ function createHtmlViteConfig(opts = {}) {
     const host = opts.host ?? '0.0.0.0';
     // 沙箱网关把 `/app/<id>` 前缀透传给 vite 时，watchdog 的 <script src>、middleware
     // 匹配路径、以及客户端 import 的 `/@vite/client` 都必须带同一前缀；空串退化到裸路径。
-    const clientBasePath = normalizeBasePath(process.env.CLIENT_BASE_PATH);
+    const clientBasePath = (0, normalize_base_path_1.normalizeBasePath)(process.env.CLIENT_BASE_PATH);
     // 从 `/app/<appId>` 形态的 base path 提取 appId 给 view-context 拼真值；非该形态则
     // 留空，view-context dev 退化为从 URL 解析。
     const appId = /^\/app\/[^/]/.test(clientBasePath)
@@ -78,6 +67,8 @@ function createHtmlViteConfig(opts = {}) {
             (0, ws_watchdog_1.wsWatchdogPlugin)({ clientBasePath }),
             // base 非 `/` 时，把无尾斜杠的 `/app/<id>` 内部 rewrite 成带尾斜杠（自守卫空 base）
             (0, base_path_1.basePathRewritePlugin)(clientBasePath),
+            // 在 `${base}routes.json` 提供路由清单（与 build 产物一致）
+            (0, routes_json_1.routesJsonPlugin)({ root, clientBasePath }),
         ],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-html-devserver",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Dev/build toolchain for the miaoda-coding html (pure HTML) stack. Wraps vite (dev + HMR) behind a bin so the template never sees vite; build is pure-copy + platform-script injection + optional minify.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",