@pactor-app/module-pack 1.55.0 → 1.57.0

package/dist/index.d.cts

@@ -28,6 +28,7 @@ interface BuildModuleResult {
         assets: number;
     };
     clientBundled: boolean;
+    serverBundled: boolean;
     warnings: string[];
 }
 /** 执行模块构建全链路，返回产物摘要；失败抛 ModuleBuildError */
@@ -62,17 +63,36 @@ declare function validateModule(options?: ValidateModuleOptions): ValidateModule
 /**
  * `initModule`：目标工程接入面的一次性初始化（幂等、只新增不破坏）：
  * - 生成 pactor.module.json（已存在则跳过）；
- * - 扫描 src/pactor 生成 module/client.ts（已存在则跳过）；
+ * - 生成 module/client.ts + module/module.css（已存在则跳过）；
+ * - `--server` 时额外生成 module/server.ts 并在新建配置中写入 serverEntry / apiPrefixes；
  * - 向 package.json 注入 files / exports / scripts / peerDependencies
  *   （已存在的字段不覆盖，冲突时 warning）。
  * 绝不修改目标工程 app/、src/ 下的任何现有文件。
  */
+/** 生成的模块样式入口（与 client entry 同属脚手架，由 client.ts import） */
+declare const CLIENT_STYLES_ENTRY = "module/module.css";
+/** 默认 server 入口（仅 `init --server` 生成） */
+declare const SERVER_ENTRY = "module/server.ts";
 interface InitModuleOptions {
     /** 目标工程根（默认 cwd） */
     dir?: string;
+    /**
+     * 覆盖已存在的初始化文件（pactor.module.json / module/client.ts / 脚手架样式，
+     * --server 时含 module/server.ts）。
+     * 缺省 false 时跳过已存在文件；由 CLI 负责询问用户后传入。
+     */
+    overwrite?: boolean;
+    /**
+     * 额外生成 module/server.ts，并在新建的 pactor.module.json 中写入
+     * serverEntry 与 apiPrefixes（默认 /api/<模块 slug>）。
+     * 缺省 false：纯 DSL 模块不引入 server entry。
+     */
+    server?: boolean;
 }
 interface InitModuleResult {
     created: string[];
+    /** overwrite 时重新生成（覆盖）的文件 */
+    overwritten: string[];
     skipped: string[];
     warnings: string[];
 }
@@ -82,16 +102,24 @@ interface ActionSource {
     /** 具名导出（如 riskActions） */
     exports: string[];
 }
-/** 执行初始化，返回创建 / 跳过 / 告警清单 */
+/** 执行初始化，返回创建 / 覆盖 / 跳过 / 告警清单 */
 declare function initModule(options?: InitModuleOptions): InitModuleResult;
-/** 从包名推导模块 id：去 scope、kebab 化 */
+/** 模块 id 统一前缀（缺省自动补齐，已有则不重复添加） */
+declare const MODULE_ID_PREFIX = "pactor-app-";
+/** 从包名推导模块 id：去 scope、kebab 化、补 pactor-app- 前缀 */
 declare function deriveModuleId(name: unknown): string;
+/** 由模块 id 推导默认 API 前缀：/api/<去掉 pactor-app- 前缀的 slug> */
+declare function deriveApiPrefix(moduleId: string): string;
 /** 扫描 src/pactor/*-actions.ts 的具名导出（export const xxx） */
 declare function discoverActions(projectDir: string): ActionSource[];
 /** 检测 src/pactor/components/index.ts 是否导出 pactorComponents */
 declare function discoverComponents(projectDir: string): boolean;
 /** 生成 module/client.ts 内容（export const extensions = { components, actions }） */
 declare function renderClientEntry(hasComponents: boolean, actions: ActionSource[]): string;
+/** 生成 module/module.css 内容（模块自带样式入口，随 client bundle 打进 tgz） */
+declare function renderModuleStyles(): string;
+/** 生成 module/server.ts 内容（逻辑路径 → 方法处理函数映射） */
+declare function renderServerEntry(moduleId: string): string;
 
 /**
  * `pactor.module.json` 配置加载与校验（手写校验，避免重依赖）。
@@ -116,13 +144,24 @@ interface ModulePackConfig {
     basePath: string;
     yamlRoot: string;
     clientEntry: string;
+    /** 服务端入口（工程相对路径，如 module/server.ts）；与 apiPrefixes 成对出现 */
+    serverEntry?: string;
+    /**
+     * 模块 API 逻辑前缀（如 /api/risk-analysis）。打包时命中这些前缀的 DSL URL
+     * 会改写为 /api/modules/<id>/...，由 Shell 的通用分发入口承接。
+     */
+    apiPrefixes?: string[];
     /** init 时自动发现的 src/pactor/*-actions.ts（仅记录，client entry 自行 import） */
     actions: string[];
     publicDir: string;
     /** target profile id（如 innospots-web-shell@2） */
     target: string;
-    demo: {
-        public: boolean;
+    /**
+     * 模块级访问默认值：'public' 时构建期给未声明 public/permission 的
+     * pages / menus 补 public: true（缺省填充）；默认 'authenticated' 不改动。
+     */
+    access: {
+        default: 'public' | 'authenticated';
     };
     tailwind: TailwindConfig;
     rewrite: {
@@ -172,6 +211,8 @@ interface TargetProfile {
     rewriteAssetUrls: (id: string, version: string) => string;
     /** 禁止 basePath: "/"（Shell joinPublicPath 会产生 "//login" 这类坏路径） */
     forbidRootBasePath: boolean;
+    /** Shell 支持 `/api/modules/<moduleId>/*` 通用模块 API 分发 */
+    moduleServerApi: boolean;
 }
 
 /**
@@ -181,16 +222,23 @@ interface TargetProfile {
  */
 declare const innospotsWebShellV1: TargetProfile;
 /**
- * innospots-web-shell@2（当前默认）：Shell lazy 页面端点已修复，
+ * innospots-web-shell@2：Shell lazy 页面端点已修复，
  * 返回 PageResource 信封 { id, resourceType: "page", version, dslVersion, schema }，
  * 与 @pactor-app/app createSitemapLoader 契约对齐，lazy: true 原样保留。
  */
 declare const innospotsWebShellV2: TargetProfile;
+/**
+ * innospots-web-shell@3（当前默认）：在 @2 的页面/导航/资源契约之上，
+ * Shell 新增 `/api/modules/<moduleId>/*` 通用分发入口，支持模块把
+ * server entry（module/server.ts）打进 tgz 并由 Shell 统一承接。
+ * 未使用 serverEntry 的模块产物与 @2 完全一致。
+ */
+declare const innospotsWebShellV3: TargetProfile;
 
 /** 未知 profile 错误（信息中列出可用值） */
 declare class ProfileError extends Error {
 }
-/** 默认 target：Shell lazy 端点已修复的契约版本 */
+/** 默认 target：支持模块 server entry 的 Shell 契约版本 */
 declare const DEFAULT_TARGET: string;
 /** 全部可用 profile id（用于报错提示与文档） */
 declare function listProfiles(): string[];
@@ -252,12 +300,15 @@ declare function expandIncludes(value: unknown, ctx: ExpandContext): unknown;
  * - inlineStringLayouts：字符串形式的布局引用解析为内联布局对象；
  * - stripMenuPaths：删除菜单显式 path（运行时按 pageId 从 pages 回填）；
  * - forceInlinePages：删除页面 lazy（随 bootstrap 内联下发）；
- * - demo.public：给 pages / menus 标记 public: true（仅演示模式）。
+ * - accessDefault='public'：给未声明 public/permission 的 pages / menus 补 public: true。
  */
 interface TransformSitemapOptions {
     profile: TargetProfile;
-    /** 演示模式：pages / menus 全部标 public */
-    demoPublic: boolean;
+    /**
+     * 模块级访问默认值：'public' 时给未声明 public/permission 的 pages / menus
+     * 补 public: true（缺省填充，不覆盖显式声明）；'authenticated' 不改动。
+     */
+    accessDefault?: 'public' | 'authenticated';
     /** 解析字符串布局引用（yamlRoot 相对路径 -> 布局对象，应走 $include 展开） */
     loadLayout: (relPath: string) => unknown;
 }
@@ -299,6 +350,10 @@ interface RewriteContext {
     assetPrefix: string;
     /** 绝对 API 地址重写为相对路径（false 时仅告警不改写） */
     absoluteApiToRelative: boolean;
+    /** 模块 id（与 apiPrefixes 同时存在时，命中前缀的 API URL 改写为模块挂载路径） */
+    moduleId?: string;
+    /** 模块声明的逻辑 API 前缀（如 `/api/risk-analysis`） */
+    apiPrefixes?: string[];
 }
 interface RewriteResult {
     value: unknown;
@@ -352,6 +407,38 @@ declare function tsconfigAliases(projectDir: string): Record<string, string>;
 /** 宽松 JSONC 解析：去注释（尊重字符串字面量）与尾逗号 */
 declare function parseJsonc(text: string): unknown;
 
+/**
+ * server entry 打包（esbuild）：
+ * - `--bundle --format=esm --platform=node --target=node20`；
+ * - 产物固定为 server/index.mjs：模块包通常没有 `"type": "module"`，
+ *   若输出 .js 会被 Node 按 CJS 解析；esbuild 的 format=esm 不会自动改扩展名，
+ *   因此必须显式 outExtension；
+ * - react / next / pactor 保持 external（server 端不需要，也不该打入模块）；
+ *   Node built-in 由 platform=node 自动 external；
+ * - alias 复用 tsconfig 的 paths（如 `@/*` → `./src/*`）；
+ * - 入口必须位于工程根内，防止越界读取。
+ */
+/** 内置 externals：宿主/框架依赖，绝不打进 server bundle */
+declare const SERVER_EXTERNALS: string[];
+/** server 产物文件名（与 manifest.serverEntry 一致） */
+declare const SERVER_BUNDLE_FILE: "index.mjs";
+/** server 打包错误（入口缺失 / 越界 / 产物缺失） */
+declare class ServerBundleError extends Error {
+}
+interface BundleServerOptions {
+    projectDir: string;
+    /** 工程相对路径（配置 serverEntry） */
+    serverEntry: string;
+    /** 输出目录（绝对路径，产物为 index.mjs / index.mjs.map） */
+    outDir: string;
+}
+interface BundleServerResult {
+    bundled: true;
+    entry: typeof SERVER_BUNDLE_FILE;
+}
+/** esbuild 打包 server entry；入口不存在或越界时抛 ServerBundleError */
+declare function bundleServer(options: BundleServerOptions): BundleServerResult;
+
 /**
  * 可选 Tailwind 预编译（配置 `tailwind: { enabled, input?, scan? }`）：
  * 调用目标工程的 tailwindcss CLI（npx --no-install tailwindcss，v4 / @tailwindcss/cli），
@@ -396,6 +483,10 @@ interface ModuleManifest {
     /** 纯 DSL 模块无 client bundle 时缺省 */
     clientEntry?: 'client/index.js';
     styles?: ['client/index.css'];
+    /** 服务端入口（存在 server bundle 时输出） */
+    serverEntry?: 'server/index.mjs';
+    /** 模块 API 逻辑前缀（与 serverEntry 成对输出） */
+    apiPrefixes?: string[];
 }
 interface EmitDslInput {
     config: ModulePackConfig;
@@ -416,6 +507,8 @@ interface WriteManifestInput {
     outDir: string;
     clientEntry?: 'client/index.js';
     styles?: ['client/index.css'];
+    serverEntry?: 'server/index.mjs';
+    apiPrefixes?: string[];
     /** 追加版本推导相关的告警 */
     warnings: string[];
 }
@@ -436,4 +529,22 @@ declare function readProjectVersion(projectDir: string): string;
  */
 declare function resolvePactorVersionRange(projectDir: string, warnings: string[]): string;
 
-export { type BuildModuleOptions, type BuildModuleResult, type BundleClientOptions, type BundleClientResult, CLIENT_EXTERNALS, CONFIG_DEFAULTS, CONFIG_FILE, type CollectedSource, type CompileTailwindOptions, type CompileTailwindResult, ConfigError, DEFAULT_TARGET, INCLUDE_KEY, IncludeError, type InitModuleOptions, type InitModuleResult, ModuleBuildError, type ModuleManifest, type ModulePackConfig, ProfileError, type RewriteContext, type RewriteNavigationProfile, type RewriteResult, type TailwindConfig, type TargetProfile, type TransformSitemapOptions, type TransformSitemapResult, type ValidateModuleOptions, type ValidateModuleResult, buildModule, bundleClient, collectModuleSource, compileTailwind, deriveModuleId, discoverActions, discoverComponents, emitDsl, emitModule, expandIncludes, getProfile, initModule, innospotsWebShellV1, innospotsWebShellV2, listProfiles, loadModuleConfig, loadYamlExpanded, matchPathPattern, parseJsonc, parseYamlFile, readProjectVersion, renderClientEntry, resolvePactorVersionRange, rewriteDslUrls, rewriteNavigationTo, transformSitemap, tsconfigAliases, validateModule, writeManifest };
+/** 版本递增类型：语义化级别或显式版本号（如 2.0.0 / 2.0.0-beta.1） */
+type VersionRelease = 'major' | 'minor' | 'patch' | (string & {});
+/** 计算下一版本号；release 为 major/minor/patch 时递增，否则按显式版本号原样采用 */
+declare function bumpVersion(current: string, release: VersionRelease): string;
+interface BumpPackageVersionOptions {
+    /** 工程根目录 */
+    dir?: string;
+    /** 递增级别或显式版本号 */
+    release: VersionRelease;
+}
+interface BumpPackageVersionResult {
+    name: string;
+    from: string;
+    to: string;
+}
+/** 递增工程 package.json 的 version 并写回（保留其余字段，2 空格缩进 + 末尾换行） */
+declare function bumpPackageVersion(options: BumpPackageVersionOptions): BumpPackageVersionResult;
+
+export { type BuildModuleOptions, type BuildModuleResult, type BumpPackageVersionOptions, type BumpPackageVersionResult, type BundleClientOptions, type BundleClientResult, type BundleServerOptions, type BundleServerResult, CLIENT_EXTERNALS, CLIENT_STYLES_ENTRY, CONFIG_DEFAULTS, CONFIG_FILE, type CollectedSource, type CompileTailwindOptions, type CompileTailwindResult, ConfigError, DEFAULT_TARGET, INCLUDE_KEY, IncludeError, type InitModuleOptions, type InitModuleResult, MODULE_ID_PREFIX, ModuleBuildError, type ModuleManifest, type ModulePackConfig, ProfileError, type RewriteContext, type RewriteNavigationProfile, type RewriteResult, SERVER_BUNDLE_FILE, SERVER_ENTRY, SERVER_EXTERNALS, ServerBundleError, type TailwindConfig, type TargetProfile, type TransformSitemapOptions, type TransformSitemapResult, type ValidateModuleOptions, type ValidateModuleResult, type VersionRelease, buildModule, bumpPackageVersion, bumpVersion, bundleClient, bundleServer, collectModuleSource, compileTailwind, deriveApiPrefix, deriveModuleId, discoverActions, discoverComponents, emitDsl, emitModule, expandIncludes, getProfile, initModule, innospotsWebShellV1, innospotsWebShellV2, innospotsWebShellV3, listProfiles, loadModuleConfig, loadYamlExpanded, matchPathPattern, parseJsonc, parseYamlFile, readProjectVersion, renderClientEntry, renderModuleStyles, renderServerEntry, resolvePactorVersionRange, rewriteDslUrls, rewriteNavigationTo, transformSitemap, tsconfigAliases, validateModule, writeManifest };

package/dist/index.d.ts

@@ -28,6 +28,7 @@ interface BuildModuleResult {
         assets: number;
     };
     clientBundled: boolean;
+    serverBundled: boolean;
     warnings: string[];
 }
 /** 执行模块构建全链路，返回产物摘要；失败抛 ModuleBuildError */
@@ -62,17 +63,36 @@ declare function validateModule(options?: ValidateModuleOptions): ValidateModule
 /**
  * `initModule`：目标工程接入面的一次性初始化（幂等、只新增不破坏）：
  * - 生成 pactor.module.json（已存在则跳过）；
- * - 扫描 src/pactor 生成 module/client.ts（已存在则跳过）；
+ * - 生成 module/client.ts + module/module.css（已存在则跳过）；
+ * - `--server` 时额外生成 module/server.ts 并在新建配置中写入 serverEntry / apiPrefixes；
  * - 向 package.json 注入 files / exports / scripts / peerDependencies
  *   （已存在的字段不覆盖，冲突时 warning）。
  * 绝不修改目标工程 app/、src/ 下的任何现有文件。
  */
+/** 生成的模块样式入口（与 client entry 同属脚手架，由 client.ts import） */
+declare const CLIENT_STYLES_ENTRY = "module/module.css";
+/** 默认 server 入口（仅 `init --server` 生成） */
+declare const SERVER_ENTRY = "module/server.ts";
 interface InitModuleOptions {
     /** 目标工程根（默认 cwd） */
     dir?: string;
+    /**
+     * 覆盖已存在的初始化文件（pactor.module.json / module/client.ts / 脚手架样式，
+     * --server 时含 module/server.ts）。
+     * 缺省 false 时跳过已存在文件；由 CLI 负责询问用户后传入。
+     */
+    overwrite?: boolean;
+    /**
+     * 额外生成 module/server.ts，并在新建的 pactor.module.json 中写入
+     * serverEntry 与 apiPrefixes（默认 /api/<模块 slug>）。
+     * 缺省 false：纯 DSL 模块不引入 server entry。
+     */
+    server?: boolean;
 }
 interface InitModuleResult {
     created: string[];
+    /** overwrite 时重新生成（覆盖）的文件 */
+    overwritten: string[];
     skipped: string[];
     warnings: string[];
 }
@@ -82,16 +102,24 @@ interface ActionSource {
     /** 具名导出（如 riskActions） */
     exports: string[];
 }
-/** 执行初始化，返回创建 / 跳过 / 告警清单 */
+/** 执行初始化，返回创建 / 覆盖 / 跳过 / 告警清单 */
 declare function initModule(options?: InitModuleOptions): InitModuleResult;
-/** 从包名推导模块 id：去 scope、kebab 化 */
+/** 模块 id 统一前缀（缺省自动补齐，已有则不重复添加） */
+declare const MODULE_ID_PREFIX = "pactor-app-";
+/** 从包名推导模块 id：去 scope、kebab 化、补 pactor-app- 前缀 */
 declare function deriveModuleId(name: unknown): string;
+/** 由模块 id 推导默认 API 前缀：/api/<去掉 pactor-app- 前缀的 slug> */
+declare function deriveApiPrefix(moduleId: string): string;
 /** 扫描 src/pactor/*-actions.ts 的具名导出（export const xxx） */
 declare function discoverActions(projectDir: string): ActionSource[];
 /** 检测 src/pactor/components/index.ts 是否导出 pactorComponents */
 declare function discoverComponents(projectDir: string): boolean;
 /** 生成 module/client.ts 内容（export const extensions = { components, actions }） */
 declare function renderClientEntry(hasComponents: boolean, actions: ActionSource[]): string;
+/** 生成 module/module.css 内容（模块自带样式入口，随 client bundle 打进 tgz） */
+declare function renderModuleStyles(): string;
+/** 生成 module/server.ts 内容（逻辑路径 → 方法处理函数映射） */
+declare function renderServerEntry(moduleId: string): string;
 
 /**
  * `pactor.module.json` 配置加载与校验（手写校验，避免重依赖）。
@@ -116,13 +144,24 @@ interface ModulePackConfig {
     basePath: string;
     yamlRoot: string;
     clientEntry: string;
+    /** 服务端入口（工程相对路径，如 module/server.ts）；与 apiPrefixes 成对出现 */
+    serverEntry?: string;
+    /**
+     * 模块 API 逻辑前缀（如 /api/risk-analysis）。打包时命中这些前缀的 DSL URL
+     * 会改写为 /api/modules/<id>/...，由 Shell 的通用分发入口承接。
+     */
+    apiPrefixes?: string[];
     /** init 时自动发现的 src/pactor/*-actions.ts（仅记录，client entry 自行 import） */
     actions: string[];
     publicDir: string;
     /** target profile id（如 innospots-web-shell@2） */
     target: string;
-    demo: {
-        public: boolean;
+    /**
+     * 模块级访问默认值：'public' 时构建期给未声明 public/permission 的
+     * pages / menus 补 public: true（缺省填充）；默认 'authenticated' 不改动。
+     */
+    access: {
+        default: 'public' | 'authenticated';
     };
     tailwind: TailwindConfig;
     rewrite: {
@@ -172,6 +211,8 @@ interface TargetProfile {
     rewriteAssetUrls: (id: string, version: string) => string;
     /** 禁止 basePath: "/"（Shell joinPublicPath 会产生 "//login" 这类坏路径） */
     forbidRootBasePath: boolean;
+    /** Shell 支持 `/api/modules/<moduleId>/*` 通用模块 API 分发 */
+    moduleServerApi: boolean;
 }
 
 /**
@@ -181,16 +222,23 @@ interface TargetProfile {
  */
 declare const innospotsWebShellV1: TargetProfile;
 /**
- * innospots-web-shell@2（当前默认）：Shell lazy 页面端点已修复，
+ * innospots-web-shell@2：Shell lazy 页面端点已修复，
  * 返回 PageResource 信封 { id, resourceType: "page", version, dslVersion, schema }，
  * 与 @pactor-app/app createSitemapLoader 契约对齐，lazy: true 原样保留。
  */
 declare const innospotsWebShellV2: TargetProfile;
+/**
+ * innospots-web-shell@3（当前默认）：在 @2 的页面/导航/资源契约之上，
+ * Shell 新增 `/api/modules/<moduleId>/*` 通用分发入口，支持模块把
+ * server entry（module/server.ts）打进 tgz 并由 Shell 统一承接。
+ * 未使用 serverEntry 的模块产物与 @2 完全一致。
+ */
+declare const innospotsWebShellV3: TargetProfile;
 
 /** 未知 profile 错误（信息中列出可用值） */
 declare class ProfileError extends Error {
 }
-/** 默认 target：Shell lazy 端点已修复的契约版本 */
+/** 默认 target：支持模块 server entry 的 Shell 契约版本 */
 declare const DEFAULT_TARGET: string;
 /** 全部可用 profile id（用于报错提示与文档） */
 declare function listProfiles(): string[];
@@ -252,12 +300,15 @@ declare function expandIncludes(value: unknown, ctx: ExpandContext): unknown;
  * - inlineStringLayouts：字符串形式的布局引用解析为内联布局对象；
  * - stripMenuPaths：删除菜单显式 path（运行时按 pageId 从 pages 回填）；
  * - forceInlinePages：删除页面 lazy（随 bootstrap 内联下发）；
- * - demo.public：给 pages / menus 标记 public: true（仅演示模式）。
+ * - accessDefault='public'：给未声明 public/permission 的 pages / menus 补 public: true。
  */
 interface TransformSitemapOptions {
     profile: TargetProfile;
-    /** 演示模式：pages / menus 全部标 public */
-    demoPublic: boolean;
+    /**
+     * 模块级访问默认值：'public' 时给未声明 public/permission 的 pages / menus
+     * 补 public: true（缺省填充，不覆盖显式声明）；'authenticated' 不改动。
+     */
+    accessDefault?: 'public' | 'authenticated';
     /** 解析字符串布局引用（yamlRoot 相对路径 -> 布局对象，应走 $include 展开） */
     loadLayout: (relPath: string) => unknown;
 }
@@ -299,6 +350,10 @@ interface RewriteContext {
     assetPrefix: string;
     /** 绝对 API 地址重写为相对路径（false 时仅告警不改写） */
     absoluteApiToRelative: boolean;
+    /** 模块 id（与 apiPrefixes 同时存在时，命中前缀的 API URL 改写为模块挂载路径） */
+    moduleId?: string;
+    /** 模块声明的逻辑 API 前缀（如 `/api/risk-analysis`） */
+    apiPrefixes?: string[];
 }
 interface RewriteResult {
     value: unknown;
@@ -352,6 +407,38 @@ declare function tsconfigAliases(projectDir: string): Record<string, string>;
 /** 宽松 JSONC 解析：去注释（尊重字符串字面量）与尾逗号 */
 declare function parseJsonc(text: string): unknown;
 
+/**
+ * server entry 打包（esbuild）：
+ * - `--bundle --format=esm --platform=node --target=node20`；
+ * - 产物固定为 server/index.mjs：模块包通常没有 `"type": "module"`，
+ *   若输出 .js 会被 Node 按 CJS 解析；esbuild 的 format=esm 不会自动改扩展名，
+ *   因此必须显式 outExtension；
+ * - react / next / pactor 保持 external（server 端不需要，也不该打入模块）；
+ *   Node built-in 由 platform=node 自动 external；
+ * - alias 复用 tsconfig 的 paths（如 `@/*` → `./src/*`）；
+ * - 入口必须位于工程根内，防止越界读取。
+ */
+/** 内置 externals：宿主/框架依赖，绝不打进 server bundle */
+declare const SERVER_EXTERNALS: string[];
+/** server 产物文件名（与 manifest.serverEntry 一致） */
+declare const SERVER_BUNDLE_FILE: "index.mjs";
+/** server 打包错误（入口缺失 / 越界 / 产物缺失） */
+declare class ServerBundleError extends Error {
+}
+interface BundleServerOptions {
+    projectDir: string;
+    /** 工程相对路径（配置 serverEntry） */
+    serverEntry: string;
+    /** 输出目录（绝对路径，产物为 index.mjs / index.mjs.map） */
+    outDir: string;
+}
+interface BundleServerResult {
+    bundled: true;
+    entry: typeof SERVER_BUNDLE_FILE;
+}
+/** esbuild 打包 server entry；入口不存在或越界时抛 ServerBundleError */
+declare function bundleServer(options: BundleServerOptions): BundleServerResult;
+
 /**
  * 可选 Tailwind 预编译（配置 `tailwind: { enabled, input?, scan? }`）：
  * 调用目标工程的 tailwindcss CLI（npx --no-install tailwindcss，v4 / @tailwindcss/cli），
@@ -396,6 +483,10 @@ interface ModuleManifest {
     /** 纯 DSL 模块无 client bundle 时缺省 */
     clientEntry?: 'client/index.js';
     styles?: ['client/index.css'];
+    /** 服务端入口（存在 server bundle 时输出） */
+    serverEntry?: 'server/index.mjs';
+    /** 模块 API 逻辑前缀（与 serverEntry 成对输出） */
+    apiPrefixes?: string[];
 }
 interface EmitDslInput {
     config: ModulePackConfig;
@@ -416,6 +507,8 @@ interface WriteManifestInput {
     outDir: string;
     clientEntry?: 'client/index.js';
     styles?: ['client/index.css'];
+    serverEntry?: 'server/index.mjs';
+    apiPrefixes?: string[];
     /** 追加版本推导相关的告警 */
     warnings: string[];
 }
@@ -436,4 +529,22 @@ declare function readProjectVersion(projectDir: string): string;
  */
 declare function resolvePactorVersionRange(projectDir: string, warnings: string[]): string;
 
-export { type BuildModuleOptions, type BuildModuleResult, type BundleClientOptions, type BundleClientResult, CLIENT_EXTERNALS, CONFIG_DEFAULTS, CONFIG_FILE, type CollectedSource, type CompileTailwindOptions, type CompileTailwindResult, ConfigError, DEFAULT_TARGET, INCLUDE_KEY, IncludeError, type InitModuleOptions, type InitModuleResult, ModuleBuildError, type ModuleManifest, type ModulePackConfig, ProfileError, type RewriteContext, type RewriteNavigationProfile, type RewriteResult, type TailwindConfig, type TargetProfile, type TransformSitemapOptions, type TransformSitemapResult, type ValidateModuleOptions, type ValidateModuleResult, buildModule, bundleClient, collectModuleSource, compileTailwind, deriveModuleId, discoverActions, discoverComponents, emitDsl, emitModule, expandIncludes, getProfile, initModule, innospotsWebShellV1, innospotsWebShellV2, listProfiles, loadModuleConfig, loadYamlExpanded, matchPathPattern, parseJsonc, parseYamlFile, readProjectVersion, renderClientEntry, resolvePactorVersionRange, rewriteDslUrls, rewriteNavigationTo, transformSitemap, tsconfigAliases, validateModule, writeManifest };
+/** 版本递增类型：语义化级别或显式版本号（如 2.0.0 / 2.0.0-beta.1） */
+type VersionRelease = 'major' | 'minor' | 'patch' | (string & {});
+/** 计算下一版本号；release 为 major/minor/patch 时递增，否则按显式版本号原样采用 */
+declare function bumpVersion(current: string, release: VersionRelease): string;
+interface BumpPackageVersionOptions {
+    /** 工程根目录 */
+    dir?: string;
+    /** 递增级别或显式版本号 */
+    release: VersionRelease;
+}
+interface BumpPackageVersionResult {
+    name: string;
+    from: string;
+    to: string;
+}
+/** 递增工程 package.json 的 version 并写回（保留其余字段，2 空格缩进 + 末尾换行） */
+declare function bumpPackageVersion(options: BumpPackageVersionOptions): BumpPackageVersionResult;
+
+export { type BuildModuleOptions, type BuildModuleResult, type BumpPackageVersionOptions, type BumpPackageVersionResult, type BundleClientOptions, type BundleClientResult, type BundleServerOptions, type BundleServerResult, CLIENT_EXTERNALS, CLIENT_STYLES_ENTRY, CONFIG_DEFAULTS, CONFIG_FILE, type CollectedSource, type CompileTailwindOptions, type CompileTailwindResult, ConfigError, DEFAULT_TARGET, INCLUDE_KEY, IncludeError, type InitModuleOptions, type InitModuleResult, MODULE_ID_PREFIX, ModuleBuildError, type ModuleManifest, type ModulePackConfig, ProfileError, type RewriteContext, type RewriteNavigationProfile, type RewriteResult, SERVER_BUNDLE_FILE, SERVER_ENTRY, SERVER_EXTERNALS, ServerBundleError, type TailwindConfig, type TargetProfile, type TransformSitemapOptions, type TransformSitemapResult, type ValidateModuleOptions, type ValidateModuleResult, type VersionRelease, buildModule, bumpPackageVersion, bumpVersion, bundleClient, bundleServer, collectModuleSource, compileTailwind, deriveApiPrefix, deriveModuleId, discoverActions, discoverComponents, emitDsl, emitModule, expandIncludes, getProfile, initModule, innospotsWebShellV1, innospotsWebShellV2, innospotsWebShellV3, listProfiles, loadModuleConfig, loadYamlExpanded, matchPathPattern, parseJsonc, parseYamlFile, readProjectVersion, renderClientEntry, renderModuleStyles, renderServerEntry, resolvePactorVersionRange, rewriteDslUrls, rewriteNavigationTo, transformSitemap, tsconfigAliases, validateModule, writeManifest };