@pactor-app/module-pack 0.0.0-stage → 1.56.0

package/dist/index.d.cts

@@ -0,0 +1,550 @@
+/**
+ * `buildModule`：模块构建全链路编排。
+ *
+ * 收集 → $include 展开 → sitemap 转换（profile）→ URL 重写 → client bundle →
+ * Tailwind 预编译 → manifest/assets 落盘 → 产物校验。
+ *
+ * 失败即阻断：全部产物先写入工程根下的临时目录，校验通过后才整体替换
+ * dist-module/；任一页面缺失或校验失败抛 ModuleBuildError，不留半成品。
+ */
+/** 构建失败（含结构化错误列表，如页面缺失 / 校验失败） */
+declare class ModuleBuildError extends Error {
+    readonly errors: string[];
+    constructor(message: string, errors: string[]);
+}
+interface BuildModuleOptions {
+    /** 目标工程根（默认 cwd） */
+    dir?: string;
+    /** 配置文件路径（默认 pactor.module.json） */
+    config?: string;
+}
+interface BuildModuleResult {
+    /** 产物目录（绝对路径） */
+    outDir: string;
+    stats: {
+        pages: number;
+        menus: number;
+        layouts: number;
+        assets: number;
+    };
+    clientBundled: boolean;
+    serverBundled: boolean;
+    warnings: string[];
+}
+/** 执行模块构建全链路，返回产物摘要；失败抛 ModuleBuildError */
+declare function buildModule(options?: BuildModuleOptions): BuildModuleResult;
+
+/**
+ * 产物校验（`pactor module validate`，构建收尾也会自动执行）：
+ * - manifest 合法且字段齐备（Manifest V1）；
+ * - sitemap 每个 pages[].id 在 dslRoot 下存在对应 <id>.yaml（与 Shell 装配器同语义，递归查找）；
+ * - 产物中无 $include 残留；
+ * - layouts 全部为对象（无字符串引用残留）；
+ * - client bundle 存在且未内嵌 react / @pactor-app（启发式扫描）；
+ * - package.json exports 含 ./manifest 与 ./client。
+ * 输出结构化错误 / 警告列表；有错误时 ok = false。
+ */
+interface ValidateModuleOptions {
+    /** 目标工程根（默认 cwd） */
+    dir?: string;
+    /** 配置文件路径（默认 pactor.module.json） */
+    config?: string;
+    /** 直接指定产物目录（构建流程内部用于校验临时目录；缺省为 <dir>/<outDir>） */
+    moduleDir?: string;
+}
+interface ValidateModuleResult {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** 校验产物目录与工程 package.json，返回结构化结果 */
+declare function validateModule(options?: ValidateModuleOptions): ValidateModuleResult;
+
+/**
+ * `initModule`：目标工程接入面的一次性初始化（幂等、只新增不破坏）：
+ * - 生成 pactor.module.json（已存在则跳过）；
+ * - 生成 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[];
+}
+interface ActionSource {
+    /** 工程相对导入路径（无扩展名，如 ../src/pactor/risk-actions） */
+    specifier: string;
+    /** 具名导出（如 riskActions） */
+    exports: string[];
+}
+/** 执行初始化，返回创建 / 覆盖 / 跳过 / 告警清单 */
+declare function initModule(options?: InitModuleOptions): InitModuleResult;
+/** 模块 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` 配置加载与校验（手写校验，避免重依赖）。
+ * 字段见设计文档 §3.2；未提供的字段使用合理默认值。
+ */
+/** 配置相关错误（缺失 / 解析失败 / 类型非法） */
+declare class ConfigError extends Error {
+}
+declare const CONFIG_FILE = "pactor.module.json";
+interface TailwindConfig {
+    enabled: boolean;
+    /** 自定义入口 css（工程相对路径）；缺省时生成 @import "tailwindcss" + @source */
+    input?: string;
+    /** 额外扫描目录（绝对路径或工程相对路径）；缺省扫描 dist-module/dsl 与 client 源码目录 */
+    scan?: string[];
+}
+interface ModulePackConfig {
+    /** 模块 id（进入 globalPageId 前缀与资源路径） */
+    id: string;
+    name: string;
+    /** 路由前缀（规范化保证以 / 开头、无尾斜杠） */
+    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;
+    /**
+     * 模块级访问默认值：'public' 时构建期给未声明 public/permission 的
+     * pages / menus 补 public: true（缺省填充）；默认 'authenticated' 不改动。
+     */
+    access: {
+        default: 'public' | 'authenticated';
+    };
+    tailwind: TailwindConfig;
+    rewrite: {
+        /** 绝对 API 地址重写为去 origin 的相对路径（默认 true） */
+        absoluteApiToRelative: boolean;
+    };
+    /** 产物目录（工程相对路径，默认 dist-module） */
+    outDir: string;
+}
+declare const CONFIG_DEFAULTS: {
+    readonly yamlRoot: "src/server/yaml";
+    readonly clientEntry: "module/client.ts";
+    readonly publicDir: "public";
+    readonly target: string;
+    readonly outDir: "dist-module";
+};
+/** 加载并校验工程根下的 pactor.module.json（或 --config 指定文件） */
+declare function loadModuleConfig(projectDir: string, configPath?: string): ModulePackConfig;
+
+/**
+ * Target profile：底座（Shell）装配契约的显式化描述。
+ *
+ * 若干打包转换本质上是当前 Shell 实现的缺陷规避（菜单去 path、布局内联、
+ * 去 lazy、basePath 禁止 "/")，而非永恒契约；Shell 修复后应发布新版本
+ * profile，模块侧改一行 `target` 即可重新打包，不改动适配器代码。
+ */
+/** 导航重写行为 */
+interface RewriteNavigationProfile {
+    /** 模块内绝对导航路径加 basePath 前缀 */
+    basePath: boolean;
+    /** 绝不重写 request 的 API url 与 http(s) 外链 */
+    excludeApiUrls: boolean;
+}
+interface TargetProfile {
+    /** profile 名（如 innospots-web-shell） */
+    name: string;
+    /** profile 版本（与 target 配置 `@<version>` 对应） */
+    version: number;
+    /** sitemap 中字符串形式的布局引用内联为布局对象 */
+    inlineStringLayouts: boolean;
+    /** 删除菜单显式 path（交给运行时按 pageId 从 pages 解析） */
+    stripMenuPaths: boolean;
+    /** 删除页面 lazy（页面随 bootstrap 内联下发；Shell lazy 端点修好前为 true） */
+    forceInlinePages: boolean;
+    rewriteNavigation: RewriteNavigationProfile;
+    /** 静态资源 URL 重写前缀（如 `/modules/<id>/<version>/`） */
+    rewriteAssetUrls: (id: string, version: string) => string;
+    /** 禁止 basePath: "/"（Shell joinPublicPath 会产生 "//login" 这类坏路径） */
+    forbidRootBasePath: boolean;
+    /** Shell 支持 `/api/modules/<moduleId>/*` 通用模块 API 分发 */
+    moduleServerApi: boolean;
+}
+
+/**
+ * innospots-web-shell@1：兼容 lazy 页面端点未修复的旧 Shell
+ * （端点返回 { version, pageDsl } 与 Pactor loader 期望的 resource.schema
+ * 不一致），强制页面随 bootstrap 内联下发（去掉 lazy）。
+ */
+declare const innospotsWebShellV1: TargetProfile;
+/**
+ * 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：支持模块 server entry 的 Shell 契约版本 */
+declare const DEFAULT_TARGET: string;
+/** 全部可用 profile id（用于报错提示与文档） */
+declare function listProfiles(): string[];
+/** 按 `name@version` 解析 profile；未知名抛出带可用值列表的 ProfileError */
+declare function getProfile(id: string): TargetProfile;
+
+/**
+ * 从 yamlRoot 收集模块源文件清单（与 PoC collectPages 语义一致）：
+ * - 页面：递归 `*.yaml`，排除 sitemap.yaml / *.layout.yaml / *.fragment.yaml；
+ *   页面 id 为文件名去掉 `.yaml`，再去掉可选的 `.page` 后缀；
+ * - 布局文件：*.layout.yaml；片段文件：*.fragment.yaml（仅登记，内容由 $include 引用）。
+ */
+interface CollectedSource {
+    yamlRoot: string;
+    /** pageId -> yamlRoot 相对路径 */
+    pages: Map<string, string>;
+    /** *.layout.yaml 的 yamlRoot 相对路径列表 */
+    layouts: string[];
+    /** *.fragment.yaml 的 yamlRoot 相对路径列表 */
+    fragments: string[];
+    /** 收集期警告（如页面 id 重复） */
+    warnings: string[];
+}
+/** 递归收集 yamlRoot 下的页面 / 布局 / 片段文件 */
+declare function collectModuleSource(yamlRoot: string): CollectedSource;
+
+/**
+ * `$include` 展开器（语义以 PoC build-adapter.mjs 为蓝本）：
+ * - `$include` 必须是对象唯一键，值为 yamlRoot 相对路径字符串；
+ * - 递归展开，循环引用报错并带引用链；
+ * - 解析失败的错误均带文件上下文。
+ *
+ * 注意：`$include` 目前是应用层约定（各工程在自己的 sitemap.ts 中重复实现），
+ * 本实现是上游化为框架能力的第一步，后续应迁移到 dsl-io 供运行时与打包共用。
+ */
+declare const INCLUDE_KEY = "$include";
+/** include 展开相关错误（循环引用 / 非法 $include / YAML 语法错误） */
+declare class IncludeError extends Error {
+}
+/** 解析 YAML 文件为 JS 值，语法错误带文件路径 */
+declare function parseYamlFile(file: string): unknown;
+interface ExpandContext {
+    yamlRoot: string;
+    /** 当前文件（yamlRoot 相对路径，用于错误信息） */
+    current: string;
+    /** 引用链（yamlRoot 相对路径），用于循环检测 */
+    stack: string[];
+}
+/**
+ * 加载 yamlRoot 下的相对路径文件并递归展开其中的 `$include`。
+ * 循环引用时报错，信息形如 `循环引用: a.yaml -> b.yaml -> a.yaml`。
+ */
+declare function loadYamlExpanded(yamlRoot: string, relPath: string, stack?: string[]): unknown;
+/** 递归展开值中的 `$include` 节点（非 $include 对象/数组/标量原样递归返回） */
+declare function expandIncludes(value: unknown, ctx: ExpandContext): unknown;
+
+/**
+ * 按 target profile 转换 sitemap（语义以 PoC 为蓝本，全部由 profile 显式开关）：
+ * - inlineStringLayouts：字符串形式的布局引用解析为内联布局对象；
+ * - stripMenuPaths：删除菜单显式 path（运行时按 pageId 从 pages 回填）；
+ * - forceInlinePages：删除页面 lazy（随 bootstrap 内联下发）；
+ * - accessDefault='public'：给未声明 public/permission 的 pages / menus 补 public: true。
+ */
+interface TransformSitemapOptions {
+    profile: TargetProfile;
+    /**
+     * 模块级访问默认值：'public' 时给未声明 public/permission 的 pages / menus
+     * 补 public: true（缺省填充，不覆盖显式声明）；'authenticated' 不改动。
+     */
+    accessDefault?: 'public' | 'authenticated';
+    /** 解析字符串布局引用（yamlRoot 相对路径 -> 布局对象，应走 $include 展开） */
+    loadLayout: (relPath: string) => unknown;
+}
+interface TransformSitemapResult {
+    site: Record<string, unknown>;
+    layoutCount: number;
+    pageCount: number;
+    menuCount: number;
+}
+type AnyRecord = Record<string, unknown>;
+/** 转换 sitemap（不修改入参，返回新对象） */
+declare function transformSitemap(site: AnyRecord, options: TransformSitemapOptions): TransformSitemapResult;
+
+/**
+ * DSL URL 重写（Shell 装配器不重写 DSL，必须在打包侧处理）：
+ *
+ * - 导航重写：action 为 `navigate` / `app.reload` 的节点，其 `params.to`
+ *   若以 `/` 开头且命中模块内页面路径或 loginPath，加 basePath 前缀；
+ *   绝不重写 `request` 的 API `url`（`/api/...`）与 http(s) 外链。
+ * - 资源重写：字符串值以 `/` 开头、非 `/api/`、非页面路径，且对应文件存在于
+ *   publicDir（如 `/next.svg`），重写为 `/modules/<id>/<version>/<path>`。
+ * - 绝对 API 地址（如 `http://localhost:8011/api/...`）：记入 warning 列表；
+ *   默认重写为去掉 origin 的相对路径（可由配置关闭）。
+ */
+interface RewriteContext {
+    /** 模块 basePath（已规范化为 `/xxx`，无尾斜杠） */
+    basePath: string;
+    /** sitemap 中全部页面 path（可含 `:param` 段） */
+    pagePaths: string[];
+    /** 登录页路径（sitemap auth.loginPath，默认 /login） */
+    loginPath: string;
+    /** 目标工程 public 目录（绝对路径，用于判断资源文件存在） */
+    publicDir: string;
+    /** 是否执行导航重写（profile.rewriteNavigation.basePath） */
+    rewriteNavigation: boolean;
+    /** 是否执行资源重写 */
+    rewriteAssets: boolean;
+    /** 资源重写前缀（如 `/modules/risk/0.1.0`，无尾斜杠） */
+    assetPrefix: string;
+    /** 绝对 API 地址重写为相对路径（false 时仅告警不改写） */
+    absoluteApiToRelative: boolean;
+    /** 模块 id（与 apiPrefixes 同时存在时，命中前缀的 API URL 改写为模块挂载路径） */
+    moduleId?: string;
+    /** 模块声明的逻辑 API 前缀（如 `/api/risk-analysis`） */
+    apiPrefixes?: string[];
+}
+interface RewriteResult {
+    value: unknown;
+    warnings: string[];
+}
+/** 遍历 DSL 值并重写 URL（不修改入参，返回新值与告警列表） */
+declare function rewriteDslUrls(value: unknown, ctx: RewriteContext): RewriteResult;
+/**
+ * 导航 `to` 重写：命中模块内页面路径或 loginPath 时加 basePath 前缀；
+ * 返回 undefined 表示不重写。模板表达式段（`${...}`）按原样保留。
+ */
+declare function rewriteNavigationTo(to: string, ctx: RewriteContext): string | undefined;
+/**
+ * 路径模式匹配：`:param` 段匹配任意非空段（含 `${...}` 模板段），
+ * 字面值段必须相等；忽略查询串。
+ */
+declare function matchPathPattern(pattern: string, value: string): boolean;
+
+/**
+ * client entry 打包（esbuild）：
+ * - `--bundle --format=esm --platform=browser`，react / react-dom / next /
+ *   pactor-app / @pactor-app/* 全部 external（peer 单例契约，防双实例）；
+ * - alias 自动从目标工程 tsconfig.json 的 compilerOptions.paths 生成（如 `@/*` → `./src/*`）；
+ * - 产出 client/index.js + sourcemap；入口引入的 CSS 由 esbuild 收集为 client/index.css；
+ * - client entry 不存在时跳过（纯 DSL 模块合法），由调用方提示。
+ */
+/** 内置 externals：peer 单例，绝不打进 bundle */
+declare const CLIENT_EXTERNALS: string[];
+interface BundleClientOptions {
+    projectDir: string;
+    /** 工程相对路径（配置 clientEntry） */
+    clientEntry: string;
+    /** 输出目录（绝对路径，产物为 index.js / index.js.map / 可能的 index.css） */
+    outDir: string;
+}
+interface BundleClientResult {
+    bundled: boolean;
+    /** 是否产出 index.css（esbuild 收集的 side-effect CSS） */
+    css: boolean;
+    /** 跳过打包时的说明（纯 DSL 模块） */
+    message?: string;
+}
+/** esbuild 打包 client entry；入口不存在时跳过打包 */
+declare function bundleClient(options: BundleClientOptions): BundleClientResult;
+/**
+ * 从目标工程 tsconfig.json 的 compilerOptions.paths 生成 esbuild alias。
+ * 支持 `@/*` -> `./src/*` 通配（alias 为去掉 `/*` 的包名）与精确映射；
+ * 沿 `extends`（相对路径）合并，子配置覆盖父配置。
+ */
+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），
+ * 扫描 dist-module/dsl 与 client 源码生成工具类 CSS，合并进 client/index.css。
+ * tailwind 不可用或编译失败时降级为 warning，不 fail 构建。
+ */
+interface CompileTailwindOptions {
+    projectDir: string;
+    tailwind: TailwindConfig;
+    /** 默认扫描目录（dist-module/dsl 产物目录 + client entry 源码目录） */
+    scanDirs: string[];
+    /** 目标 CSS 文件（client/index.css，不存在则创建） */
+    cssFile: string;
+}
+interface CompileTailwindResult {
+    compiled: boolean;
+    warnings: string[];
+}
+/** 执行 Tailwind 预编译并把工具类 CSS 追加到 cssFile */
+declare function compileTailwind(options: CompileTailwindOptions): CompileTailwindResult;
+
+/**
+ * 产物落盘：dist-module/ = Manifest V1 + dsl/（sitemap + 页面 DSL）+
+ * assets/（public 复制）+ module-assets.json（sha256 清单）+ client/（由 bundle 阶段写入）。
+ *
+ * Manifest V1 契约对齐 Shell 装配器（assemble-modules.mjs）：
+ * require.resolve("<pkg>/manifest") → manifest.json；pages[].id ↔ dslRoot 下
+ * <pageId>.yaml；assetsRoot 复制到 public/modules/<id>/<version>/。
+ */
+interface ModuleManifest {
+    schemaVersion: '1';
+    id: string;
+    name: string;
+    /** 与目标工程 package.json version 同步 */
+    version: string;
+    /** 从目标工程安装的 pactor-app 版本推导（如 ^1.54.0） */
+    pactorVersionRange: string;
+    basePath: string;
+    sitemap: 'dsl/sitemap.yaml';
+    dslRoot: 'dsl';
+    assetsRoot: 'assets';
+    /** 纯 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;
+    projectDir: string;
+    /** 产物目录（绝对路径，通常是临时构建目录） */
+    outDir: string;
+    /** 转换 + 重写后的 sitemap */
+    site: Record<string, unknown>;
+    /** pageId -> 展开 + 重写后的页面 DSL */
+    pages: Map<string, unknown>;
+}
+interface EmitDslResult {
+    assetCount: number;
+}
+interface WriteManifestInput {
+    config: ModulePackConfig;
+    projectDir: string;
+    outDir: string;
+    clientEntry?: 'client/index.js';
+    styles?: ['client/index.css'];
+    serverEntry?: 'server/index.mjs';
+    apiPrefixes?: string[];
+    /** 追加版本推导相关的告警 */
+    warnings: string[];
+}
+/** 一步落盘全部产物（dsl + assets + module-assets.json + manifest.json） */
+declare function emitModule(input: EmitDslInput & Omit<WriteManifestInput, 'config' | 'projectDir' | 'outDir'>): EmitDslResult & {
+    manifest: ModuleManifest;
+};
+/** 落盘 dsl/（sitemap.yaml + <pageId>.yaml）与 assets/（含 module-assets.json） */
+declare function emitDsl(input: EmitDslInput): EmitDslResult;
+/** 生成 manifest.json（version 与目标工程 package.json 同步） */
+declare function writeManifest(input: WriteManifestInput): ModuleManifest;
+/** 读取目标工程 package.json 的 version（缺失时回退 0.0.0） */
+declare function readProjectVersion(projectDir: string): string;
+/**
+ * 推导 pactorVersionRange：优先目标工程 node_modules 中实际安装的
+ * pactor-app / @pactor-app/app 版本（^x.y.z）；其次 package.json 中声明的
+ * 版本范围；都不可得时告警并回退 ^1.54.0。
+ */
+declare function resolvePactorVersionRange(projectDir: string, warnings: string[]): string;
+
+/** 版本递增类型：语义化级别或显式版本号（如 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 };