snapshot-checker 0.2.2 → 0.3.1

package/dist/src/lib/{common_groups.d.ts → presets.d.ts}

@@ -32,9 +32,15 @@ export declare function decodeRawPerfDataAndWriteOutputs(input: {
     inputFilePath: string;
     dumpStackTxt: string;
     dumpStackJson: string;
+    dumpStackXlsx: string;
     traceFormatProfile: string;
     stageName: string;
-}): boolean;
+    skipDedupePerfData?: boolean;
+    /** 解码 trace 后是否执行 {@link associateFsVfs}（在 dedupe 之前） */
+    runAssociateFsVfs?: boolean;
+    /** 传入 {@link decodePerfRawData}：丢弃有 raw 但无对应 trace 解析器的样本 */
+    dropFailedSamples?: boolean;
+}): Promise<boolean>;
 type DecodeInputConfig = {
     inputFilePath: string;
     inputContextKey?: never;
@@ -50,9 +56,14 @@ export declare function buildCommonAnalysisGroup(input: {
     decodeInput: DecodeInputConfig;
     dumpStackTxt: string;
     dumpStackJson: string;
+    dumpStackXlsx: string;
     traceFormatProfile: string;
     decodeStageName: string;
     missingInputMessage: string;
+    skipDedupePerfData?: boolean;
+    runAssociateFsVfs?: boolean;
+    /** 传入 {@link decodePerfRawData}：丢弃有 raw 但无对应 trace 解析器的样本 */
+    dropFailedSamples?: boolean;
 }): CommandDef[];
 export {};
-//# sourceMappingURL=common_groups.d.ts.map
+//# sourceMappingURL=presets.d.ts.map

package/dist/src/lib/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/lib/presets.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,aAAa,CAAC;AAa9D,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAc/D,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B,GAAG,UAAU,EAAE,CAkDf;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6BAA6B,EAAE,MAAM,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GAAG,UAAU,EAAE,CAmBf;AAED,wBAAgB,oCAAoC,CAAC,KAAK,EAAE;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;CAC/B,GAAG,UAAU,EAAE,CA0Df;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,QAAQ,GAAG,SAAS,CAavB;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAYA;AAED,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CASA;AAED,wBAAsB,gCAAgC,CAAC,KAAK,EAAE;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,OAAO,CAAC,OAAO,CAAC,CAsFnB;AAED,KAAK,iBAAiB,GAClB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,KAAK,CAAA;CAAE,GAClD;IAAE,aAAa,CAAC,EAAE,KAAK,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,UAAU,EAAE,CAAC;IACjC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,UAAU,EAAE,CAmDf"}

package/dist/src/lib/{common_groups.js → presets.js}

@@ -1,7 +1,14 @@
+/** forkall / report 等场景复用的命令组拼装与 perf 解码辅助 */
+import { logger } from "../logger.js";
 import { CommandKind } from "../types.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { buildTraceParserRegistry, decodePerfRawData, filterByTgid, formatPerfDataToJson, formatPerfDataToText, parsePerfData, toBackTraceStacks, } from "hiperf_txt_parser";
-import { getTraceEventFormatProfiles, getTraceEventFormats, } from "./trace_formatter.js";
+import { buildTraceParserRegistry, decodePerfRawData, dedupePerfData, filterByTgid, formatPerfDataToExcel, formatPerfDataToJson, formatPerfDataToText, parsePerfData, toBackTraceStacks, } from "hiperf_txt_parser";
+import { associateFsVfs, getTraceEventFormatProfiles, getTraceEventFormats, setHmtraceLogger, } from "hmtrace-parser";
+setHmtraceLogger({
+    trace: (msg) => logger.trace(msg),
+    debug: (msg) => logger.debug(msg),
+    info: (msg) => logger.info(msg),
+});
 export function buildCommonInitEnvGroup(input) {
     const { app, snapshotLogFile, checkStateCommand, permissionCommands } = input;
     const permissionDefs = permissionCommands.map((run) => ({
@@ -37,7 +44,7 @@ export function buildCommonInitEnvGroup(input) {
         {
             kind: CommandKind.Windows,
             description: "删除应用镜像",
-            run: `hdc shell hidumper -s 1901 -a '-p libforkall_plugin.z.so --delete ${app}'`,
+            run: `hdc shell "hidumper -s 1901 -a '-p libforkall_plugin.z.so --destroy 100 ${app}'"`,
         },
         {
             kind: CommandKind.Windows,
@@ -47,7 +54,7 @@ export function buildCommonInitEnvGroup(input) {
         {
             kind: CommandKind.Windows,
             description: "配置模式开关",
-            run: 'hdc shell "echo 1:0000 > /proc/checkpoint/revoke_switch && echo checkout_witch "',
+            run: 'hdc shell "echo 0:0000 > /proc/checkpoint/revoke_switch && echo 1:0000 > /proc/checkpoint/revoke_switch && echo 2:0000 > /proc/checkpoint/revoke_switch && cat /proc/checkpoint/revoke_switch"',
         },
         ...permissionDefs,
     ];
@@ -88,24 +95,24 @@ export function buildCommonAnalysisTargetFilterGroup(input) {
             func: (ctx) => {
                 const targetTgidRaw = ctx.get("target_tgid");
                 if (!targetTgidRaw) {
-                    console.warn("[过滤目标数据] 未获取到 target_tgid，跳过数据过滤");
+                    logger.warn("[过滤目标数据] 未获取到 target_tgid，跳过数据过滤");
                     return false;
                 }
                 const targetTgid = parseInt(targetTgidRaw, 10);
                 if (Number.isNaN(targetTgid)) {
-                    console.error(`[过滤目标数据] target_tgid 非法: ${targetTgidRaw}`);
+                    logger.error(`[过滤目标数据] target_tgid 非法: ${targetTgidRaw}`);
                     return false;
                 }
                 try {
                     if (!existsSync(snapshotPerfFile)) {
-                        console.warn(`[过滤目标数据] 输入文件不存在，跳过处理: ${snapshotPerfFile}`);
+                        logger.warn(`[过滤目标数据] 输入文件不存在，跳过处理: ${snapshotPerfFile}`);
                         return false;
                     }
                     const inputText = readFileSync(snapshotPerfFile, "utf-8");
                     const recordSamples = parsePerfData(inputText);
                     const filteredRecordSamples = filterByTgid(recordSamples, targetTgid);
                     if (filteredRecordSamples.recordSamples.length === 0) {
-                        console.error(`[过滤目标数据] filterByTgid 后无样本数据（tgid=${targetTgid}），终止流程`);
+                        logger.error(`[过滤目标数据] filterByTgid 后无样本数据（tgid=${targetTgid}），终止流程`);
                         return false;
                     }
                     const samplesToWrite = writeBacktraceStacks
@@ -113,10 +120,10 @@ export function buildCommonAnalysisTargetFilterGroup(input) {
                         : filteredRecordSamples;
                     const filteredRecordSamplesTxt = formatPerfDataToText(samplesToWrite);
                     writeFileSync(snapshotPerfFile, filteredRecordSamplesTxt, "utf-8");
-                    console.info(`[过滤目标数据] 处理完成并写回文件: ${snapshotPerfFile}`);
+                    logger.info(`[过滤目标数据] 处理完成并写回文件: ${snapshotPerfFile}`);
                 }
                 catch (error) {
-                    console.error(`[过滤目标数据] 处理失败: ${snapshotPerfFile}`, error);
+                    logger.error(`[过滤目标数据] 处理失败: ${snapshotPerfFile}`, error);
                     return false;
                 }
             },
@@ -126,7 +133,7 @@ export function buildCommonAnalysisTargetFilterGroup(input) {
 export function readPerfDataOrWarn(input) {
     const { filePath, stageName } = input;
     if (!existsSync(filePath)) {
-        console.warn(`[${stageName}] 输入文件不存在，跳过处理: ${filePath}`);
+        logger.warn(`[${stageName}] 输入文件不存在，跳过处理: ${filePath}`);
         return undefined;
     }
     try {
@@ -134,7 +141,7 @@ export function readPerfDataOrWarn(input) {
         return parsePerfData(inputText);
     }
     catch (error) {
-        console.error(`[${stageName}] 读取或解析失败: ${filePath}`, error);
+        logger.error(`[${stageName}] 读取或解析失败: ${filePath}`, error);
         return undefined;
     }
 }
@@ -158,19 +165,19 @@ export function selectFirstValidPerfInput(candidates) {
         if (valid) {
             return { filePath };
         }
-        console.warn(`[选择 perf 输入] 跳过文件: ${filePath}，原因: ${reason}`);
+        logger.warn(`[选择 perf 输入] 跳过文件: ${filePath}，原因: ${reason}`);
     }
     return { reason: "未找到可用 perf 输入文件" };
 }
-export function decodeRawPerfDataAndWriteOutputs(input) {
-    const { inputFilePath, dumpStackTxt, dumpStackJson, traceFormatProfile, stageName, } = input;
+export async function decodeRawPerfDataAndWriteOutputs(input) {
+    const { inputFilePath, dumpStackTxt, dumpStackJson, dumpStackXlsx, traceFormatProfile, stageName, skipDedupePerfData = false, runAssociateFsVfs = false, dropFailedSamples = false, } = input;
     try {
         const availableProfiles = getTraceEventFormatProfiles();
         const selectedProfile = availableProfiles.includes(traceFormatProfile)
             ? traceFormatProfile
             : "default";
         if (selectedProfile !== traceFormatProfile) {
-            console.warn(`[${stageName}] 未识别 trace-format-profile="${traceFormatProfile}"，已回退到 default`);
+            logger.warn(`[${stageName}] 未识别 trace-format-profile="${traceFormatProfile}"，已回退到 default`);
         }
         const traceParser = buildTraceParserRegistry(getTraceEventFormats(selectedProfile));
         const recordSamples = readPerfDataOrWarn({
@@ -182,21 +189,52 @@ export function decodeRawPerfDataAndWriteOutputs(input) {
         }
         const parsedRecordSamples = decodePerfRawData(recordSamples, traceParser, {
             tracePrintMode: "fieldDict",
+            dropFailedSamples,
         });
-        const recordSamplesJson = formatPerfDataToJson(parsedRecordSamples);
-        const recordSamplesTxt = formatPerfDataToText(parsedRecordSamples);
+        let dataForDedupe = parsedRecordSamples;
+        if (runAssociateFsVfs) {
+            const [associatedSamples] = associateFsVfs(parsedRecordSamples);
+            dataForDedupe = {
+                ...parsedRecordSamples,
+                recordSamples: [...associatedSamples],
+            };
+        }
+        const dedupedPerfData = skipDedupePerfData
+            ? dataForDedupe
+            : dedupePerfData(dataForDedupe, {
+                onEnd: (s) => {
+                    logger.info(`[${stageName}] perf 去重: input=${s.input}, removed=${s.removed}, remaining=${s.remaining}`);
+                },
+            });
+        const recordSamplesJson = formatPerfDataToJson(dedupedPerfData);
+        const recordSamplesTxt = formatPerfDataToText(dedupedPerfData);
         writeFileSync(dumpStackJson, JSON.stringify(recordSamplesJson, null, 2), "utf-8");
         writeFileSync(dumpStackTxt, recordSamplesTxt, "utf-8");
-        console.info(`[${stageName}] 分析完成，格式版本: ${selectedProfile}，输出文件: ${dumpStackJson}, ${dumpStackTxt}`);
+        const outputPaths = [dumpStackJson, dumpStackTxt];
+        if (dedupedPerfData.recordSamples.length === 0) {
+            logger.info(`[${stageName}] 无样本数据，跳过 Excel 导出`);
+        }
+        else {
+            try {
+                const xlsxBuffer = await formatPerfDataToExcel(dedupedPerfData);
+                writeFileSync(dumpStackXlsx, xlsxBuffer);
+                outputPaths.push(dumpStackXlsx);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.warn(`[${stageName}] Excel 导出未写入（${message}）`, error);
+            }
+        }
+        logger.info(`[${stageName}] 分析完成，格式版本: ${selectedProfile}，输出文件: ${outputPaths.join(", ")}`);
         return true;
     }
     catch (error) {
-        console.error(`[${stageName}] 处理失败`, error);
+        logger.error(`[${stageName}] 处理失败`, error);
         return false;
     }
 }
 export function buildCommonAnalysisGroup(input) {
-    const { app, snapshotPerfFile, writeBacktraceStacks, preDecodeCommands = [], decodeInput, dumpStackTxt, dumpStackJson, traceFormatProfile, decodeStageName, missingInputMessage, } = input;
+    const { app, snapshotPerfFile, writeBacktraceStacks, preDecodeCommands = [], decodeInput, dumpStackTxt, dumpStackJson, dumpStackXlsx, traceFormatProfile, decodeStageName, missingInputMessage, skipDedupePerfData = false, runAssociateFsVfs = false, dropFailedSamples = false, } = input;
     const targetFilterGroup = buildCommonAnalysisTargetFilterGroup({
         app,
         snapshotPerfFile,
@@ -205,23 +243,27 @@ export function buildCommonAnalysisGroup(input) {
     const decodeCommand = {
         kind: CommandKind.BuiltinFunction,
         description: decodeStageName,
-        func: (ctx) => {
+        func: async (ctx) => {
             const inputFilePath = decodeInput.inputContextKey != null
                 ? ctx.get(decodeInput.inputContextKey)
                 : decodeInput.inputFilePath;
             if (!inputFilePath) {
-                console.warn(missingInputMessage);
+                logger.warn(missingInputMessage);
                 return false;
             }
             return decodeRawPerfDataAndWriteOutputs({
                 inputFilePath,
                 dumpStackTxt,
                 dumpStackJson,
+                dumpStackXlsx,
                 traceFormatProfile,
                 stageName: decodeStageName,
+                skipDedupePerfData,
+                runAssociateFsVfs,
+                dropFailedSamples,
             });
         },
     };
     return [...targetFilterGroup, ...preDecodeCommands, decodeCommand];
 }
-//# sourceMappingURL=common_groups.js.map
+//# sourceMappingURL=presets.js.map

package/dist/src/lib/presets.js.map

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

package/dist/src/lib/{programmatic.d.ts → scenario.d.ts}

@@ -1,6 +1,6 @@
 import type { GroupSpec } from "../runGroups.js";
 import type { CommandResult, Groups } from "../types.js";
-/** 与 commands/*.ts 场景模块兼容的最小形状 */
+/** 与 `commands/*.ts` 场景模块导出面兼容的最小接口 */
 export interface ScenarioModuleLike {
     groups: Groups;
     defaultGroupOrder: string[];
@@ -13,13 +13,9 @@ export interface ScenarioModuleLike {
         defaultGroupOrder?: string[];
     } | void;
 }
-/**
- * 将 Commander 的 variadic --group 规范为 string[]（单参时可能是单个字符串）。
- */
+/** 将 Commander 的 variadic `--group` 归一化为 `string[]`（单参数时可能为单个字符串） */
 export declare function normalizeGroupCliArg(groupRaw: string[] | string | undefined): string[] | undefined;
-/**
- * 若场景导出 applyOptions，则根据 scenarioOptions 得到最终 groups / defaultGroupOrder。
- */
+/** 若模块导出 `applyOptions`，则按 `scenarioOptions` 生成最终的 `groups` 与 `defaultGroupOrder` */
 export declare function resolveScenario(mod: ScenarioModuleLike, scenarioOptions?: Record<string, unknown>): {
     groups: Groups;
     defaultGroupOrder: string[];
@@ -27,14 +23,16 @@ export declare function resolveScenario(mod: ScenarioModuleLike, scenarioOptions
 export interface RunScenarioGroupsInput {
     groups: Groups;
     defaultGroupOrder: string[];
-    /** 等价 CLI -g/--group，不传则按 defaultGroupOrder 顺序各执行 1 次 */
+    /** 与 CLI `-g` / `--group` 相同；缺省时按 `defaultGroupOrder` 各执行一次 */
     group?: string[] | string;
-    /** 直接指定组规格时优先于 group / defaultGroupOrder 的默认展开 */
+    /** 显式组规格时覆盖由 `group` 与 `defaultGroupOrder` 推导的结果 */
     groupSpecs?: GroupSpec[];
     ignorePlatform?: boolean;
     stopOnError?: boolean;
+    /** 见 `RunOptions.silent` */
     silent?: boolean;
     waitForBackground?: boolean;
+    /** 见 `RunOptions.intervalMs` */
     intervalMs?: number;
 }
 export interface RunScenarioGroupsResult {
@@ -42,7 +40,7 @@ export interface RunScenarioGroupsResult {
     failed: boolean;
 }
 /**
- * 按组规格执行命令（与 CLI 非 list/dry-run 路径一致）。
+ * 按组规格执行命令；语义与 CLI 在排除 `--list`、`--dry-run` 时的执行路径一致。
  */
 export declare function runScenarioGroups(input: RunScenarioGroupsInput): Promise<RunScenarioGroupsResult>;
-//# sourceMappingURL=programmatic.d.ts.map
+//# sourceMappingURL=scenario.d.ts.map

package/dist/src/lib/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"","sources":["../../../src/lib/scenario.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEzD,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,KAAK;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC9B,GAAG,IAAI,CAAC;CACV;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,GACtC,MAAM,EAAE,GAAG,SAAS,CAGtB;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAC7B,GAAG,EAAE,kBAAkB,EACvB,eAAe,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAC5C;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAcjD;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CA2BlC"}

package/dist/src/lib/{programmatic.js → scenario.js}

@@ -1,7 +1,7 @@
 /**
- * 程序化 API：在代码中复用与 CLI 相同的场景解析与组执行能力。
+ * 编程方式复用 CLI 的场景解析与按组执行逻辑。
  *
- * 典型用法：
+ * 示例：
  * ```ts
  * import { resolveScenario, runScenarioGroups } from 'snapshot-checker';
  * import * as report from './commands/report.js';
@@ -16,17 +16,13 @@
  */
 import { getGroupChunks, runGroupChunks, } from "../runGroups.js";
 import { parseGroupSpecs } from "../groupSpecs.js";
-/**
- * 将 Commander 的 variadic --group 规范为 string[]（单参时可能是单个字符串）。
- */
+/** 将 Commander 的 variadic `--group` 归一化为 `string[]`（单参数时可能为单个字符串） */
 export function normalizeGroupCliArg(groupRaw) {
     if (groupRaw === undefined || groupRaw === null)
         return undefined;
     return Array.isArray(groupRaw) ? groupRaw : [String(groupRaw)];
 }
-/**
- * 若场景导出 applyOptions，则根据 scenarioOptions 得到最终 groups / defaultGroupOrder。
- */
+/** 若模块导出 `applyOptions`，则按 `scenarioOptions` 生成最终的 `groups` 与 `defaultGroupOrder` */
 export function resolveScenario(mod, scenarioOptions = {}) {
     let groups = mod.groups;
     let defaultGroupOrder = mod.defaultGroupOrder;
@@ -44,7 +40,7 @@ export function resolveScenario(mod, scenarioOptions = {}) {
     return { groups, defaultGroupOrder };
 }
 /**
- * 按组规格执行命令（与 CLI 非 list/dry-run 路径一致）。
+ * 按组规格执行命令；语义与 CLI 在排除 `--list`、`--dry-run` 时的执行路径一致。
  */
 export async function runScenarioGroups(input) {
     const { groups, defaultGroupOrder, group, groupSpecs: explicitSpecs, ignorePlatform = false, stopOnError = false, silent = false, waitForBackground = false, intervalMs, } = input;
@@ -60,4 +56,4 @@ export async function runScenarioGroups(input) {
     };
     return runGroupChunks(chunks, options);
 }
-//# sourceMappingURL=programmatic.js.map
+//# sourceMappingURL=scenario.js.map

package/dist/src/lib/scenario.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.js","sourceRoot":"","sources":["../../../src/lib/scenario.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,cAAc,EACd,cAAc,GAEf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAiBnD,qEAAqE;AACrE,MAAM,UAAU,oBAAoB,CAClC,QAAuC;IAEvC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAC7B,GAAuB,EACvB,kBAA2C,EAAE;IAE7C,IAAI,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IACxB,IAAI,iBAAiB,GAAG,GAAG,CAAC,iBAAiB,CAAC;IAC9C,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QAC3C,MAAM,WAAW,GAAG,GAAG,CAAC,YAAY,CAAC;YACnC,MAAM;YACN,iBAAiB;YACjB,OAAO,EAAE,eAAe;SACzB,CAAC,CAAC;QACH,IAAI,WAAW,EAAE,MAAM;YAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;QACrD,IAAI,WAAW,EAAE,iBAAiB;YAChC,iBAAiB,GAAG,WAAW,CAAC,iBAAiB,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;AACvC,CAAC;AAuBD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAA6B;IAE7B,MAAM,EACJ,MAAM,EACN,iBAAiB,EACjB,KAAK,EACL,UAAU,EAAE,aAAa,EACzB,cAAc,GAAG,KAAK,EACtB,WAAW,GAAG,KAAK,EACnB,MAAM,GAAG,KAAK,EACd,iBAAiB,GAAG,KAAK,EACzB,UAAU,GACX,GAAG,KAAK,CAAC;IAEV,MAAM,KAAK,GACT,aAAa;QACb,eAAe,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAElE,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC;IACjE,MAAM,OAAO,GAA0B;QACrC,WAAW;QACX,MAAM;QACN,iBAAiB;QACjB,cAAc;QACd,UAAU,EACR,UAAU,KAAK,SAAS,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;KACtE,CAAC;IACF,OAAO,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/src/logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 工具侧结构化日志；子进程标准流由 Shell 等 Runner 与 `streamOutput` 控制。
+ *
+ * 默认级别由 `SNAPSHOT_CHECKER_LOG_LEVEL` 或 `LOG_LEVEL` 给出（与 `hiperf_txt_parser` 同名枚举；未识别时回退为 `info`），并与 {@link setHiperfLogLevel} 对齐。
+ * CLI 全局 `--log-level` 通过 {@link setGlobalLogLevelFromCli} 覆盖该基准（直至进程退出）。
+ */
+import { type ConsolaInstance } from "consola";
+import { type HiperfLogLevelName } from "hiperf_txt_parser";
+/** 与 `hiperf_txt_parser` 一致的合法级别（供 CLI choices 与环境解析共用） */
+export declare const SNAPSHOT_CHECKER_LOG_LEVEL_CHOICES: readonly HiperfLogLevelName[];
+/**
+ * 由 CLI 全局 `--log-level` 在子命令 `preAction` 中调用，覆盖环境变量给出的基准。
+ */
+export declare function setGlobalLogLevelFromCli(level: string | undefined): void;
+/**
+ * 按 `silent` 进入嵌套静默：将日志与 `hiperf_txt_parser` 限制为 `error`，可多次嵌套计数。
+ *
+ * @returns 结束当前作用域时须调用的恢复函数。
+ */
+export declare function attachQuietSilent(silent: boolean): () => void;
+/** 全局共享的 Consola 实例；未处于 {@link attachQuietSilent} 时与 {@link baselineLevelName} 一致 */
+export declare const logger: ConsolaInstance;
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,2DAA2D;AAC3D,eAAO,MAAM,kCAAkC,EAAE,SAAS,kBAAkB,EAOlE,CAAC;AAsCX;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAUxE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,CAmB7D;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM,EAAE,eAEnB,CAAC"}

package/dist/src/logger.js

@@ -0,0 +1,92 @@
+/**
+ * 工具侧结构化日志；子进程标准流由 Shell 等 Runner 与 `streamOutput` 控制。
+ *
+ * 默认级别由 `SNAPSHOT_CHECKER_LOG_LEVEL` 或 `LOG_LEVEL` 给出（与 `hiperf_txt_parser` 同名枚举；未识别时回退为 `info`），并与 {@link setHiperfLogLevel} 对齐。
+ * CLI 全局 `--log-level` 通过 {@link setGlobalLogLevelFromCli} 覆盖该基准（直至进程退出）。
+ */
+import { createConsola, LogLevels } from "consola";
+import { setHiperfLogLevel, } from "hiperf_txt_parser";
+/** 与 `hiperf_txt_parser` 一致的合法级别（供 CLI choices 与环境解析共用） */
+export const SNAPSHOT_CHECKER_LOG_LEVEL_CHOICES = [
+    "silent",
+    "error",
+    "warn",
+    "info",
+    "debug",
+    "trace",
+];
+function resolveHiperfLevelNameFromEnv() {
+    const raw = (process.env.SNAPSHOT_CHECKER_LOG_LEVEL ??
+        process.env.LOG_LEVEL ??
+        "info")
+        .trim()
+        .toLowerCase();
+    return SNAPSHOT_CHECKER_LOG_LEVEL_CHOICES.includes(raw)
+        ? raw
+        : "info";
+}
+/** 基准级别：初始为环境变量；可被 {@link setGlobalLogLevelFromCli} 覆盖（不含 {@link attachQuietSilent} 嵌套降噪） */
+let baselineLevelName = resolveHiperfLevelNameFromEnv();
+setHiperfLogLevel(baselineLevelName);
+const LEVEL_TO_CONSOLA = {
+    silent: LogLevels.silent,
+    error: LogLevels.error,
+    warn: LogLevels.warn,
+    info: LogLevels.info,
+    debug: LogLevels.debug,
+    trace: LogLevels.trace,
+};
+/** `RunOptions.silent` / CLI `-s` 时与 consola、`hiperf_txt_parser` 对齐的静默级别标识 */
+const QUIET_HIPEXF_NAME = "error";
+let quietSilentDepth = 0;
+/** 恢复 {@link baselineLevelName}，并同步 `hiperf_txt_parser`。 */
+function applySyncedLevels() {
+    logger.level = LEVEL_TO_CONSOLA[baselineLevelName];
+    setHiperfLogLevel(baselineLevelName);
+}
+/**
+ * 由 CLI 全局 `--log-level` 在子命令 `preAction` 中调用，覆盖环境变量给出的基准。
+ */
+export function setGlobalLogLevelFromCli(level) {
+    if (level === undefined || level === "")
+        return;
+    const raw = level.trim().toLowerCase();
+    if (!SNAPSHOT_CHECKER_LOG_LEVEL_CHOICES.includes(raw)) {
+        return;
+    }
+    baselineLevelName = raw;
+    if (quietSilentDepth === 0) {
+        applySyncedLevels();
+    }
+}
+/**
+ * 按 `silent` 进入嵌套静默：将日志与 `hiperf_txt_parser` 限制为 `error`，可多次嵌套计数。
+ *
+ * @returns 结束当前作用域时须调用的恢复函数。
+ */
+export function attachQuietSilent(silent) {
+    if (!silent) {
+        return () => { };
+    }
+    quietSilentDepth += 1;
+    if (quietSilentDepth === 1) {
+        logger.level = LogLevels.error;
+        setHiperfLogLevel(QUIET_HIPEXF_NAME);
+    }
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        quietSilentDepth -= 1;
+        if (quietSilentDepth <= 0) {
+            quietSilentDepth = 0;
+            applySyncedLevels();
+        }
+    };
+}
+/** 全局共享的 Consola 实例；未处于 {@link attachQuietSilent} 时与 {@link baselineLevelName} 一致 */
+export const logger = createConsola({
+    level: LEVEL_TO_CONSOLA[baselineLevelName],
+});
+//# sourceMappingURL=logger.js.map

package/dist/src/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,SAAS,EAAwB,MAAM,SAAS,CAAC;AACzE,OAAO,EACL,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAE3B,2DAA2D;AAC3D,MAAM,CAAC,MAAM,kCAAkC,GAAkC;IAC/E,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;CACC,CAAC;AAEX,SAAS,6BAA6B;IACpC,MAAM,GAAG,GAAG,CACV,OAAO,CAAC,GAAG,CAAC,0BAA0B;QACtC,OAAO,CAAC,GAAG,CAAC,SAAS;QACrB,MAAM,CACP;SACE,IAAI,EAAE;SACN,WAAW,EAAE,CAAC;IACjB,OAAQ,kCAAwD,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC5E,CAAC,CAAE,GAA0B;QAC7B,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED,6FAA6F;AAC7F,IAAI,iBAAiB,GAAuB,6BAA6B,EAAE,CAAC;AAC5E,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;AAErC,MAAM,gBAAgB,GAAuC;IAC3D,MAAM,EAAE,SAAS,CAAC,MAAM;IACxB,KAAK,EAAE,SAAS,CAAC,KAAK;IACtB,IAAI,EAAE,SAAS,CAAC,IAAI;IACpB,IAAI,EAAE,SAAS,CAAC,IAAI;IACpB,KAAK,EAAE,SAAS,CAAC,KAAK;IACtB,KAAK,EAAE,SAAS,CAAC,KAAK;CACvB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,iBAAiB,GAAG,OAAoC,CAAC;AAC/D,IAAI,gBAAgB,GAAG,CAAC,CAAC;AAEzB,4DAA4D;AAC5D,SAAS,iBAAiB;IACxB,MAAM,CAAC,KAAK,GAAG,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACnD,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAyB;IAChE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO;IAChD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAE,kCAAwD,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7E,OAAO;IACT,CAAC;IACD,iBAAiB,GAAG,GAAyB,CAAC;IAC9C,IAAI,gBAAgB,KAAK,CAAC,EAAE,CAAC;QAC3B,iBAAiB,EAAE,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAClB,CAAC;IACD,gBAAgB,IAAI,CAAC,CAAC;IACtB,IAAI,gBAAgB,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QAC/B,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,OAAO,GAAS,EAAE;QAChB,IAAI,IAAI;YAAE,OAAO;QACjB,IAAI,GAAG,IAAI,CAAC;QACZ,gBAAgB,IAAI,CAAC,CAAC;QACtB,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;YAC1B,gBAAgB,GAAG,CAAC,CAAC;YACrB,iBAAiB,EAAE,CAAC;QACtB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,MAAM,GAAoB,aAAa,CAAC;IACnD,KAAK,EAAE,gBAAgB,CAAC,iBAAiB,CAAC;CAC3C,CAAC,CAAC"}

package/dist/src/runCommand.d.ts

@@ -1,67 +1,59 @@
 /**
- * 单条命令执行模块：执行单条或按顺序执行多条命令，不涉及 group 概念。
- * 命令执行失败的判断（Mac / Linux / Windows 通用）：
- * - 进程正常退出：exitCode === 0 为成功，否则为失败
- * - 进程被信号终止（Unix）：code 为 null，视为失败
- * - spawn 报错（如找不到命令）：视为失败
+ * 单条与顺序多命令执行（不含 group 分块）。
+ *
+ * 成功与否：`exitCode === 0` 为成功；信号结束或 `spawn` 失败为失败（与平台一致）。
  */
 import { type ChildProcess } from "node:child_process";
-import type { CommandContext, CommandDef, CommandResult } from "./types.js";
-/** 当前系统是否支持该命令类型：embed 全平台；linux/mac/windows 仅对应平台 */
+import { type CommandContext, type CommandDef, type CommandResult } from "./types.js";
+/** `embed` / `builtin-function` 恒为 true；其余需与 {@link getCurrentPlatformKind} 一致 */
 export declare function isSupportedOnCurrentPlatform(cmd: CommandDef): boolean;
 export interface ExecuteOneOptions {
-    /** 是否将子进程 stdout/stderr 实时打印到当前进程；默认 true */
+    /** 为 true（默认）时转发子进程的 stdout/stderr */
     streamOutput?: boolean;
-    /** 当命令配置了 background 时，将 spawn 出的子进程传入此回调，由调用方统一管理（如结束后台时 kill） */
+    /** `background` 命令的子进程交由调用方管理（卸载、收尾等） */
     registerBackgroundProcess?: (child: ChildProcess) => void;
-    /** 传入当前命令上下文，供 builtin-function 使用 */
+    /** 参见 {@link RunnerExecuteOptions.registerPendingBackgroundSpawn} */
+    registerPendingBackgroundSpawn?: (done: Promise<void>) => void;
+    /** 内置函数的命令上下文 */
     commandContext?: CommandContext;
 }
-/** 执行单条命令 */
+/** 执行单个 {@link CommandDef} */
 export declare function executeOne(cmd: CommandDef, options?: ExecuteOneOptions): Promise<CommandResult>;
 export interface ExecuteAllOptions {
     /**
-     * 当某条命令执行失败时是否终止后续命令。
-     * 默认 false：忽略命令执行状态，继续执行后续命令。
-     * 设为 true：一旦有命令失败（exitCode !== 0 或进程被信号终止等），立即停止。
+     * 遇失败是否中止后续命令。默认 `false`：继续执行；`true`：非零退出码或信号终止即停止。
      */
     stopOnError?: boolean;
+    /**
+       * 为 `true` 时经 `attachQuietSilent`（src/logger）应用日志降噪，并协同 `hiperf_txt_parser`；
+       * 默认 `streamOutput === false`，且不将非流式缓冲结果回显至终端。
+       */
     silent?: boolean;
     /**
-     * 是否将子进程输出实时打印（非 silent 时默认 true）。
-     * 为 true 时 stdout/stderr 会边执行边输出，结束后不再重复打印整段内容。
+     * 子进程标准流是否实时输出。未指定且非 `silent` 时默认为 `true`；为 `true` 时不在结束时重复整段缓冲输出。
      */
     streamOutput?: boolean;
-    /**
-     * 进度条偏移量（用于跨块累计进度），通常由调用方内部使用。
-     * 例如前面已经执行了 5 条命令，则 offset = 5。
-     */
+    /** 当前批次首条命令在全局序列中的序位偏移（跨块累计进度） */
     offset?: number;
-    /**
-     * 所有待执行命令的总数（用于显示 cur/all）。
-     * 不传则默认使用当前批次 commands.length + offset。
-     */
+    /** 全局待执行命令总数（用于 `cur/total`）；缺省为 `commands.length + offset` */
     total?: number;
     /**
-     * 若传入，则将本批次启动的后台子进程追加到该数组，由调用方在全部任务结束后统一处理；
-     * 此时本函数不会在末尾自行 wait/kill 后台进程。
+     * 将本批次后台子进程追加至该数组，由调用方统一回收；为真时本函数末尾不处理后台进程。
      */
     aggregateBackgroundChildren?: ChildProcess[];
     /**
-     * 当未使用 aggregateBackgroundChildren 时生效：
-     * true — 等待后台进程自然退出；false — 前台结束后优雅结束后台进程。
+     * 未使用 `aggregateBackgroundChildren` 时：是否等待后台进程自然退出（否则在前台结束后终止后台进程）。
      */
     waitForBackground?: boolean;
-    /**
-     * 可选：复用并更新同一份命令上下文（跨多次 executeAll / 跨 group 传递变量）。
-     * 传入的对象会被就地写入；未传时仅在本次 executeAll 内有效。
-     */
+    /** 跨 `executeAll` / 分组复用的命令上下文；传入则原地更新 */
     commandContext?: CommandContext;
 }
 /**
- * 前台命令链结束后对后台子进程收尾：wait 为 true 则等到全部退出，否则优雅 kill。
+ * 前台队列结束后处理后台子进程：`wait === true` 时等待自然退出，否则发送终止并回收。
+ */
+export declare function finalizeBackgroundProcesses(children: ChildProcess[], wait: boolean): Promise<void>;
+/**
+ * 顺序执行命令列表；不包含组间间隔。成功/失败语义同 `executeOne`。
  */
-export declare function finalizeBackgroundProcesses(children: ChildProcess[], wait: boolean, silent: boolean): Promise<void>;
-/** 按顺序执行多条命令（无组间间隔）。失败判断见 executeOne，支持 Mac/Linux/Windows。 */
 export declare function executeAll(commands: CommandDef[], options?: ExecuteAllOptions): Promise<CommandResult[]>;
 //# sourceMappingURL=runCommand.d.ts.map

package/dist/src/runCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runCommand.d.ts","sourceRoot":"","sources":["../../src/runCommand.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAO9D,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,aAAa,EAEd,MAAM,YAAY,CAAC;AAYpB,sDAAsD;AACtD,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAOrE;AAYD,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mEAAmE;IACnE,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1D,sCAAsC;IACtC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,aAAa;AACb,wBAAsB,UAAU,CAC9B,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA4CxB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,2BAA2B,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AA8MD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,YAAY,EAAE,EACxB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,8DAA8D;AAC9D,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,aAAa,EAAE,CAAC,CAsF1B"}
+{"version":3,"file":"runCommand.d.ts","sourceRoot":"","sources":["../../src/runCommand.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAapB,kFAAkF;AAClF,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAOrE;AAYD,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC1D,qEAAqE;IACrE,8BAA8B,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;IAC/D,iBAAiB;IACjB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,8BAA8B;AAC9B,wBAAsB,UAAU,CAC9B,GAAG,EAAE,UAAU,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAkDxB;AAED,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACxB;;;SAGK;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,2BAA2B,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7C;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,0CAA0C;IAC1C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAsMD;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,YAAY,EAAE,EACxB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,aAAa,EAAE,CAAC,CA2G1B"}