soloforge 1.1.42 → 1.1.43

package/dist/shared/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Env — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：ENV 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export declare const ENV: {
+    /** 调试日志开关: 设为 "1" 启用 stderr debug 输出 */
+    readonly DEBUG: "SOLOFORGE_DEBUG";
+    /** 静默模式开关: 设为 "1" 抑制所有输出 */
+    readonly SILENT: "SOLOFORGE_SILENT";
+    /** 项目路径: 覆盖 cwd 作为项目根目录 */
+    readonly PROJECT: "SOLOFORGE_PROJECT";
+    /** 授权令牌: 配置后 tool authorization_token 必须精确匹配 */
+    readonly AUTH_TOKEN: "SOLOFORGE_AUTH_TOKEN";
+};
+//# sourceMappingURL=env.d.ts.map

package/dist/shared/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/shared/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,GAAG;IACd,wCAAwC;;IAExC,4BAA4B;;IAE5B,2BAA2B;;IAE3B,gDAAgD;;CAExC,CAAC"}

package/dist/shared/env.js

@@ -0,0 +1,24 @@
+/**
+ * Env — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：ENV 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export const ENV = {
+    /** 调试日志开关: 设为 "1" 启用 stderr debug 输出 */
+    DEBUG: "SOLOFORGE_DEBUG",
+    /** 静默模式开关: 设为 "1" 抑制所有输出 */
+    SILENT: "SOLOFORGE_SILENT",
+    /** 项目路径: 覆盖 cwd 作为项目根目录 */
+    PROJECT: "SOLOFORGE_PROJECT",
+    /** 授权令牌: 配置后 tool authorization_token 必须精确匹配 */
+    AUTH_TOKEN: "SOLOFORGE_AUTH_TOKEN",
+};
+//# sourceMappingURL=env.js.map

package/dist/shared/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/shared/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,wCAAwC;IACxC,KAAK,EAAE,iBAAiB;IACxB,4BAA4B;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,2BAA2B;IAC3B,OAAO,EAAE,mBAAmB;IAC5B,gDAAgD;IAChD,UAAU,EAAE,sBAAsB;CAC1B,CAAC"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Errors — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：SoloForgeError 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+/**
+ * SoloForge 结构化错误
+ */
+export declare class SoloForgeError extends Error {
+    /** 错误码 — 用于程序化识别错误类型 */
+    readonly code: string;
+    /** 严重性 — error 或 warning */
+    readonly severity: "error" | "warning";
+    /** 恢复建议 */
+    readonly recovery?: string;
+    constructor(message: string, code: string, severity?: "error" | "warning", recovery?: string);
+    /** 序列化为 JSON 友好格式 */
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,wBAAwB;IACxB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,4BAA4B;IAC5B,SAAgB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9C,WAAW;IACX,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,OAAO,GAAG,SAAmB,EACvC,QAAQ,CAAC,EAAE,MAAM;IASnB,qBAAqB;IACrB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC"}

package/dist/shared/errors.js

@@ -0,0 +1,42 @@
+/**
+ * Errors — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：SoloForgeError 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+/**
+ * SoloForge 结构化错误
+ */
+export class SoloForgeError extends Error {
+    /** 错误码 — 用于程序化识别错误类型 */
+    code;
+    /** 严重性 — error 或 warning */
+    severity;
+    /** 恢复建议 */
+    recovery;
+    constructor(message, code, severity = "error", recovery) {
+        super(message);
+        this.name = "SoloForgeError";
+        this.code = code;
+        this.severity = severity;
+        this.recovery = recovery;
+    }
+    /** 序列化为 JSON 友好格式 */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            severity: this.severity,
+            recovery: this.recovery,
+        };
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,wBAAwB;IACR,IAAI,CAAS;IAC7B,4BAA4B;IACZ,QAAQ,CAAsB;IAC9C,WAAW;IACK,QAAQ,CAAU;IAElC,YACE,OAAe,EACf,IAAY,EACZ,WAAgC,OAAO,EACvC,QAAiB;QAEjB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,qBAAqB;IACrB,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC;IACJ,CAAC;CACF"}

package/dist/shared/exit_codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Exit Codes — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：EXIT 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export declare const EXIT: {
+    /** 成功 */
+    readonly OK: 0;
+    /** 通用错误 */
+    readonly GENERAL: 1;
+    /** 参数错误 */
+    readonly ARGS: 2;
+    /** 配置错误 */
+    readonly CONFIG: 3;
+    /** 网络错误 */
+    readonly NETWORK: 4;
+};
+//# sourceMappingURL=exit_codes.d.ts.map

package/dist/shared/exit_codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit_codes.d.ts","sourceRoot":"","sources":["../../src/shared/exit_codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,IAAI;IACf,SAAS;;IAET,WAAW;;IAEX,WAAW;;IAEX,WAAW;;IAEX,WAAW;;CAEH,CAAC"}

package/dist/shared/exit_codes.js

@@ -0,0 +1,26 @@
+/**
+ * Exit Codes — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：EXIT 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export const EXIT = {
+    /** 成功 */
+    OK: 0,
+    /** 通用错误 */
+    GENERAL: 1,
+    /** 参数错误 */
+    ARGS: 2,
+    /** 配置错误 */
+    CONFIG: 3,
+    /** 网络错误 */
+    NETWORK: 4,
+};
+//# sourceMappingURL=exit_codes.js.map

package/dist/shared/exit_codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit_codes.js","sourceRoot":"","sources":["../../src/shared/exit_codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,SAAS;IACT,EAAE,EAAE,CAAC;IACL,WAAW;IACX,OAAO,EAAE,CAAC;IACV,WAAW;IACX,IAAI,EAAE,CAAC;IACP,WAAW;IACX,MAAM,EAAE,CAAC;IACT,WAAW;IACX,OAAO,EAAE,CAAC;CACF,CAAC"}

package/dist/shared/fail_closed.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Fail Closed — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：FailClosedResult 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+/** 区分正常缺失与异常损坏的判别联合类型 */
+export type FailClosedResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Error;
+    corrupt: true;
+};
+/** 类型守卫：结果是否正常 */
+export declare function isOk<T>(result: FailClosedResult<T>): result is {
+    ok: true;
+    value: T;
+};
+/** 类型守卫：结果是否为损坏状态 */
+export declare function isCorrupt<T>(result: FailClosedResult<T>): result is {
+    ok: false;
+    error: Error;
+    corrupt: true;
+};
+/**
+ * 安全执行读取操作，返回 FailClosedResult。
+ * 支持同步和异步读取函数。
+ *
+ * @param readFn - 读取函数（同步或异步），返回 T 或 null
+ * @param errorContext - 错误上下文描述，用于构造 Error 消息
+ * @returns FailClosedResult<T>
+ */
+export declare function failClosedRead<T>(readFn: () => T | Promise<T>, errorContext: string): FailClosedResult<T> | Promise<FailClosedResult<T>>;
+//# sourceMappingURL=fail_closed.d.ts.map

package/dist/shared/fail_closed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail_closed.d.ts","sourceRoot":"","sources":["../../src/shared/fail_closed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yBAAyB;AACzB,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC;AAE/C,kBAAkB;AAClB,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAErF;AAED,qBAAqB;AACrB,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAE9G;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5B,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAqBpD"}

package/dist/shared/fail_closed.js

@@ -0,0 +1,53 @@
+/**
+ * Fail Closed — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：FailClosedResult 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+/** 类型守卫：结果是否正常 */
+export function isOk(result) {
+    return result.ok;
+}
+/** 类型守卫：结果是否为损坏状态 */
+export function isCorrupt(result) {
+    return !result.ok;
+}
+/**
+ * 安全执行读取操作，返回 FailClosedResult。
+ * 支持同步和异步读取函数。
+ *
+ * @param readFn - 读取函数（同步或异步），返回 T 或 null
+ * @param errorContext - 错误上下文描述，用于构造 Error 消息
+ * @returns FailClosedResult<T>
+ */
+export function failClosedRead(readFn, errorContext) {
+    try {
+        const valueOrPromise = readFn();
+        // 如果返回值是 Promise，需要异步等待并捕获 rejection
+        if (valueOrPromise instanceof Promise) {
+            return valueOrPromise
+                .then((value) => ({ ok: true, value }))
+                .catch((e) => {
+                const error = e instanceof Error
+                    ? e
+                    : new Error(`${errorContext}: ${String(e)}`);
+                return { ok: false, error, corrupt: true };
+            });
+        }
+        return { ok: true, value: valueOrPromise };
+    }
+    catch (e) {
+        const error = e instanceof Error
+            ? e
+            : new Error(`${errorContext}: ${String(e)}`);
+        return { ok: false, error, corrupt: true };
+    }
+}
+//# sourceMappingURL=fail_closed.js.map

package/dist/shared/fail_closed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail_closed.js","sourceRoot":"","sources":["../../src/shared/fail_closed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,kBAAkB;AAClB,MAAM,UAAU,IAAI,CAAI,MAA2B;IACjD,OAAO,MAAM,CAAC,EAAE,CAAC;AACnB,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,SAAS,CAAI,MAA2B;IACtD,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA4B,EAC5B,YAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,EAAE,CAAC;QAChC,qCAAqC;QACrC,IAAI,cAAc,YAAY,OAAO,EAAE,CAAC;YACtC,OAAO,cAAc;iBAClB,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAA0B,CAAA,CAAC;iBAC7D,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;gBACX,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK;oBAC9B,CAAC,CAAC,CAAC;oBACH,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,YAAY,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAyB,CAAC;YACpE,CAAC,CAAC,CAAC;QACP,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;IAC7C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK;YAC9B,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,YAAY,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/shared/glob_path.d.ts

@@ -0,0 +1,45 @@
+/**
+ * glob_path — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：轻量 glob 路径匹配（仅支持单段 `*`，不跨目录）与产物路径存在性判定
+ * - 不负责：完整 glob 引擎（`**` / `?` / `[]` 不支持），那些场景应引入专用库
+ *
+ * 被谁调用：原型说明多端路径（`docs/analyze/{端}/01-原型说明.md`）等带通配符的产物路径检查
+ * 调用谁：node:fs、node:path
+ *
+ * 数据流：glob 模式 → 字符串匹配 / 文件系统遍历 → 命中结果
+ * 持久化：无持久化（纯计算 / 只读文件系统）
+ *
+ * 设计说明：原型说明等多端产物的 glob 模式是固定单层（`*` 不跨目录），
+ * 不需要完整 glob 引擎。本模块采用自研的递归遍历思路，
+ * 零第三方依赖、保持 engines.node >=18 兼容。
+ */
+/**
+ * 检测路径是否含通配符。
+ * 自研 matchGlob 只完整支持 `*`（单段）；含 `?` / `[` 时本函数仍返回 true，
+ * 但调用方应回退字面处理（见 globToRegExpSource 返回 null 的分支）。
+ */
+export declare function containsGlob(p: string): boolean;
+/**
+ * 纯字符串 glob 匹配（不碰文件系统）。
+ * 把 pattern 当 glob：`*` 匹配单段（不含 `/`）；含 `?` / `[` 时按字面全等比较（保守不误判）。
+ * 用于已知具体路径对模式判定（如 matchTemplateContract 拿用户 file_path 对 applicable_output_paths）。
+ */
+export declare function matchGlob(filePath: string, pattern: string): boolean;
+/**
+ * 判定产物路径是否存在（查文件系统·布尔）。
+ * - pattern 无通配符：直接 existsSync（字面，完全向后兼容）
+ * - pattern 含 `*`：限定到 glob 前缀子树遍历 + matchGlob，任一命中即 true
+ * - pattern 含 `?` / `[`：保守按字面 existsSync（不误判）
+ */
+export declare function artifactPathExists(rootDir: string, pattern: string): boolean;
+/**
+ * 解析产物路径到所有命中的真实相对路径（查文件系统·返回数组）。
+ * 用于多端产物聚合（如交叉校验需汇总各端 PROTO-* ID，不能只读首个）。
+ * - pattern 无通配符：存在则返回 [pattern]，否则 []
+ * - pattern 含 `*`：限定子树遍历，返回所有 matchGlob 命中的相对路径（相对 rootDir，正斜杠）
+ * - pattern 含 `?` / `[`：保守按字面
+ */
+export declare function resolveArtifactsByGlob(rootDir: string, pattern: string): string[];
+//# sourceMappingURL=glob_path.d.ts.map

package/dist/shared/glob_path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob_path.d.ts","sourceRoot":"","sources":["../../src/shared/glob_path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/C;AAwBD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAIpE;AA2CD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAU5E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAUjF"}

package/dist/shared/glob_path.js

@@ -0,0 +1,145 @@
+/**
+ * glob_path — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：轻量 glob 路径匹配（仅支持单段 `*`，不跨目录）与产物路径存在性判定
+ * - 不负责：完整 glob 引擎（`**` / `?` / `[]` 不支持），那些场景应引入专用库
+ *
+ * 被谁调用：原型说明多端路径（`docs/analyze/{端}/01-原型说明.md`）等带通配符的产物路径检查
+ * 调用谁：node:fs、node:path
+ *
+ * 数据流：glob 模式 → 字符串匹配 / 文件系统遍历 → 命中结果
+ * 持久化：无持久化（纯计算 / 只读文件系统）
+ *
+ * 设计说明：原型说明等多端产物的 glob 模式是固定单层（`*` 不跨目录），
+ * 不需要完整 glob 引擎。本模块采用自研的递归遍历思路，
+ * 零第三方依赖、保持 engines.node >=18 兼容。
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** 通配符字符集合：仅这三种视为 glob 模式（`*` / `?` / `[`） */
+const GLOB_CHARS = ["*", "?", "["];
+/** 递归遍历时应跳过的非产物目录（避免扫 node_modules / 构建产物等噪声） */
+const SCAN_EXCLUDED_DIRS = new Set(["node_modules", ".git", "dist", ".soloforge"]);
+/**
+ * 检测路径是否含通配符。
+ * 自研 matchGlob 只完整支持 `*`（单段）；含 `?` / `[` 时本函数仍返回 true，
+ * 但调用方应回退字面处理（见 globToRegExpSource 返回 null 的分支）。
+ */
+export function containsGlob(p) {
+    return GLOB_CHARS.some((ch) => p.includes(ch));
+}
+/**
+ * 把 glob 模式转成正则源字符串。
+ * - 仅处理 `*`（→ `[^/]*`，匹配单段不含路径分隔符的字符）
+ * - 含 `?` 或 `[` 时返回 null（自研引擎不完整支持，调用方回退字面）
+ * - 其余正则元字符一律转义，路径分隔符 `/` 按字面处理
+ */
+function globToRegExpSource(pattern) {
+    // 仅支持纯 * 模式；含 ? 或 [ 则返回 null 表示不处理（调用方回退字面）
+    if (pattern.includes("?") || pattern.includes("["))
+        return null;
+    let src = "^";
+    for (const ch of pattern) {
+        if (ch === "*") {
+            src += "[^/]*";
+        }
+        else if (/[$^()+.\\|{}]/.test(ch)) {
+            src += "\\" + ch;
+        }
+        else {
+            src += ch;
+        }
+    }
+    return src + "$";
+}
+/**
+ * 纯字符串 glob 匹配（不碰文件系统）。
+ * 把 pattern 当 glob：`*` 匹配单段（不含 `/`）；含 `?` / `[` 时按字面全等比较（保守不误判）。
+ * 用于已知具体路径对模式判定（如 matchTemplateContract 拿用户 file_path 对 applicable_output_paths）。
+ */
+export function matchGlob(filePath, pattern) {
+    const src = globToRegExpSource(pattern);
+    if (src === null)
+        return filePath === pattern; // 含 ? / [ ：保守字面全等
+    return new RegExp(src).test(filePath);
+}
+/**
+ * 从 glob 模式提取首个 `*` 之前的固定目录前缀（相对 rootDir）。
+ * 例：`docs/analyze/{端}/01-原型说明.md` → `docs/analyze`（只遍历该子树，避免扫全项目）。
+ */
+function globSearchSubdir(pattern) {
+    const starIdx = pattern.indexOf("*");
+    const prefix = starIdx >= 0 ? pattern.slice(0, starIdx) : "";
+    const lastSlash = prefix.lastIndexOf("/");
+    return lastSlash >= 0 ? prefix.slice(0, lastSlash) : "";
+}
+/**
+ * 递归遍历 rootDir 下指定子目录，返回所有文件的相对路径（相对 rootDir，正斜杠）。
+ * 跳过 node_modules / .git / dist / .soloforge 等非产物目录。
+ */
+function collectFilesFrom(rootDir, searchSubdir) {
+    const startAbs = path.join(rootDir, searchSubdir);
+    const results = [];
+    if (!fs.existsSync(startAbs))
+        return results;
+    const stack = [startAbs];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue; // 无权限或被删除的目录，跳过
+        }
+        for (const entry of entries) {
+            const absolutePath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (SCAN_EXCLUDED_DIRS.has(entry.name))
+                    continue;
+                stack.push(absolutePath);
+            }
+            else {
+                results.push(path.relative(rootDir, absolutePath).replace(/\\/g, "/"));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * 判定产物路径是否存在（查文件系统·布尔）。
+ * - pattern 无通配符：直接 existsSync（字面，完全向后兼容）
+ * - pattern 含 `*`：限定到 glob 前缀子树遍历 + matchGlob，任一命中即 true
+ * - pattern 含 `?` / `[`：保守按字面 existsSync（不误判）
+ */
+export function artifactPathExists(rootDir, pattern) {
+    if (!containsGlob(pattern)) {
+        return fs.existsSync(path.join(rootDir, pattern));
+    }
+    const src = globToRegExpSource(pattern);
+    if (src === null) {
+        return fs.existsSync(path.join(rootDir, pattern)); // 含 ? / [ ：保守字面
+    }
+    const re = new RegExp(src);
+    return collectFilesFrom(rootDir, globSearchSubdir(pattern)).some((f) => re.test(f));
+}
+/**
+ * 解析产物路径到所有命中的真实相对路径（查文件系统·返回数组）。
+ * 用于多端产物聚合（如交叉校验需汇总各端 PROTO-* ID，不能只读首个）。
+ * - pattern 无通配符：存在则返回 [pattern]，否则 []
+ * - pattern 含 `*`：限定子树遍历，返回所有 matchGlob 命中的相对路径（相对 rootDir，正斜杠）
+ * - pattern 含 `?` / `[`：保守按字面
+ */
+export function resolveArtifactsByGlob(rootDir, pattern) {
+    if (!containsGlob(pattern)) {
+        return fs.existsSync(path.join(rootDir, pattern)) ? [pattern] : [];
+    }
+    const src = globToRegExpSource(pattern);
+    if (src === null) {
+        return fs.existsSync(path.join(rootDir, pattern)) ? [pattern] : [];
+    }
+    const re = new RegExp(src);
+    return collectFilesFrom(rootDir, globSearchSubdir(pattern)).filter((f) => re.test(f));
+}
+//# sourceMappingURL=glob_path.js.map

package/dist/shared/glob_path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob_path.js","sourceRoot":"","sources":["../../src/shared/glob_path.ts"],"names":[],"mappings":"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"}

package/dist/shared/helpers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Helpers — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：safeMatchIndex 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export declare function safeMatchIndex(m: RegExpMatchArray): number;
+/**
+ * Safe replacement for `match.groups!.xxx` — returns empty object as fallback.
+ */
+export declare function safeMatchGroups(m: RegExpMatchArray): Record<string, string>;
+/**
+ * 统一 unknown 错误为字符串。
+ * 替代分散在 48+ 处的 `e instanceof Error ? e.message : String(e)` 模式。
+ * 如果是 SoloForgeError 且包含 recovery 建议，自动拼接恢复提示。
+ */
+export declare function errorMessage(e: unknown): string;
+/**
+ * 安全的 JSON 解析 — 替代裸 `JSON.parse()`。
+ * 解析失败时返回 fallback（默认 undefined），不会抛出异常。
+ *
+ * CORE-011: 类型安全说明：
+ * - 不提供 fallback 时，返回 T | undefined — 调用方必须处理 undefined 情况
+ * - 提供 fallback 时，返回 T（fallback 本身就是 T 类型）
+ * - 如果传入 non-null assertion (!) 跳过 undefined 检查，属于调用方责任
+ *
+ * 重载签名:
+ * - safeJsonParse(text) → T | undefined （不提供 fallback，解析失败返回 undefined）
+ * - safeJsonParse<T>(text, fallback) → T （提供 fallback，解析失败返回 fallback 值）
+ */
+export declare function safeJsonParse<T>(text: string): T | undefined;
+export declare function safeJsonParse<T>(text: string, fallback: T): T;
+/**
+ * 安全的 JSON 序列化 — 替代裸 `JSON.stringify()`。
+ * 循环引用或其他错误时返回 fallback（默认 undefined）。
+ */
+export declare function safeJsonStringify(obj: unknown, fallback?: string): string | undefined;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/shared/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/shared/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAE1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAW/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;AAC9D,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;AAS/D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrF"}

package/dist/shared/helpers.js

@@ -0,0 +1,60 @@
+/**
+ * Helpers — 核心基础层模块。
+ *
+ * 职责边界：
+ * - 负责：safeMatchIndex 等 核心基础层职责
+ * - 不负责：不属于本模块的职责由对应模块承担
+ *
+ * 被谁调用：引擎各子模块、管线层
+ * 调用谁：无外部依赖
+ *
+ * 数据流：底层能力请求 → 处理 → 返回结果
+ * 持久化：无持久化（纯计算/内存态）
+ */
+export function safeMatchIndex(m) {
+    return typeof m.index === "number" ? m.index : 0;
+}
+/**
+ * Safe replacement for `match.groups!.xxx` — returns empty object as fallback.
+ */
+export function safeMatchGroups(m) {
+    return (m.groups ?? {});
+}
+/**
+ * 统一 unknown 错误为字符串。
+ * 替代分散在 48+ 处的 `e instanceof Error ? e.message : String(e)` 模式。
+ * 如果是 SoloForgeError 且包含 recovery 建议，自动拼接恢复提示。
+ */
+export function errorMessage(e) {
+    if (e instanceof Error) {
+        // 检查 SoloForgeError 的 recovery 字段 — 提供可操作的恢复建议
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const sfe = e;
+        if (sfe.recovery && typeof sfe.recovery === "string") {
+            return `${e.message} [恢复建议: ${sfe.recovery}]`;
+        }
+        return e.message;
+    }
+    return String(e);
+}
+export function safeJsonParse(text, fallback) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * 安全的 JSON 序列化 — 替代裸 `JSON.stringify()`。
+ * 循环引用或其他错误时返回 fallback（默认 undefined）。
+ */
+export function safeJsonStringify(obj, fallback) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return fallback;
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/shared/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/shared/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,cAAc,CAAC,CAAmB;IAChD,OAAO,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,CAAmB;IACjD,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAA2B,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,+CAA+C;QAC/C,8DAA8D;QAC9D,MAAM,GAAG,GAAG,CAAQ,CAAC;QACrB,IAAI,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACrD,OAAO,GAAG,CAAC,CAAC,OAAO,WAAW,GAAG,CAAC,QAAQ,GAAG,CAAC;QAChD,CAAC;QACD,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC;AAiBD,MAAM,UAAU,aAAa,CAAI,IAAY,EAAE,QAAY;IACzD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,QAAiB;IAC/D,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}