@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/core/test/background-runs.js

@@ -1,5 +1,5 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d5f2c177-4eed-5bc5-89b5-3c5d689f902a")}catch{}})();import fs from"node:fs/promises";import{spawn}from"node:child_process";import{createHash,randomBytes}from"node:crypto";import path from"node:path";import{ensureDir,pathExists,readFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{PmCliError}from"../shared/errors.js";import{EXIT_CODE}from"../shared/constants.js";import{nowIso}from"../shared/time.js";import{getTestRunRecordPath,getTestRunResultPath,getTestRunStderrPath,getTestRunStdoutPath,getTestRunsPath,getTestRunsRecordsPath,getTestRunsResultsPath,getTestRunsStderrPath,getTestRunsStdoutPath}from"../store/paths.js";const BACKGROUND_RUN_ACTIVE_STATUSES=new Set(["queued","running"]),BACKGROUND_RUN_TERMINAL_STATUSES=new Set(["passed","failed","stopped","canceled"]),DEFAULT_BACKGROUND_RUN_RESOURCE_SNAPSHOT_INTERVAL_MS=3e3,DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS=3e3,DEFAULT_BACKGROUND_RUN_HEARTBEAT_STALE_MS=3e4,DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES=100,PROC_STAT_TICKS_PER_SECOND=100;function nowMs(){return Date.now()}function normalizeCommandArgs(args){return args.map(entry=>entry.trim()).filter(entry=>entry.length>0)}function summarizeCommandLabel(args){const joined=args.join(" ").replaceAll(/\s+/g," ").trim();return joined.length<=180?joined:`${joined.slice(0,177)}...`}function buildRunId(){const timePart=Date.now().toString(36),randomPart=randomBytes(3).toString("hex");return`tr-${timePart}-${randomPart}`}function buildBackgroundTestRunFingerprint(kind,commandArgs,pmRoot){const payload={kind,command:normalizeCommandArgs(commandArgs),pm_root:path.resolve(pmRoot)};return createHash("sha256").update(JSON.stringify(payload)).digest("hex")}function isPidRunning(pid){if(!Number.isInteger(pid)||!pid||pid<=0)return!1;try{return process.kill(pid,0),!0}catch(error){return(typeof error=="object"&&error!==null&&"code"in error?error.code:void 0)==="EPERM"}}async function ensureBackgroundRunStorage(pmRoot){await ensureDir(getTestRunsPath(pmRoot)),await ensureDir(getTestRunsRecordsPath(pmRoot)),await ensureDir(getTestRunsStdoutPath(pmRoot)),await ensureDir(getTestRunsStderrPath(pmRoot)),await ensureDir(getTestRunsResultsPath(pmRoot))}async function parseBackgroundRunRecord(raw,recordPath){try{const parsed=JSON.parse(raw);if(!parsed||typeof parsed!="object"||typeof parsed.id!="string")throw new Error("invalid run record payload");return parsed}catch(error){throw new PmCliError(`Failed to parse background test run record at ${recordPath}: ${error instanceof Error?error.message:String(error)}`,EXIT_CODE.GENERIC_FAILURE)}}async function writeBackgroundRunRecord(pmRoot,record){const next={...record,updated_at:nowIso()};await writeFileAtomic(getTestRunRecordPath(pmRoot,record.id),`${JSON.stringify(next,null,2)}
-`)}async function readBackgroundTestRunRecord(pmRoot,runId){const recordPath=getTestRunRecordPath(pmRoot,runId),raw=await readFileIfExists(recordPath);return raw?parseBackgroundRunRecord(raw,recordPath):null}async function listBackgroundRunRecordPaths(pmRoot){const recordsRoot=getTestRunsRecordsPath(pmRoot);return await pathExists(recordsRoot)?(await fs.readdir(recordsRoot,{withFileTypes:!0})).filter(entry=>entry.isFile()&&entry.name.endsWith(".json")).map(entry=>path.join(recordsRoot,entry.name)).sort((left,right)=>right.localeCompare(left)):[]}function parseLinuxRssStatus(raw){const match=raw.match(/^VmRSS:\s+(\d+)\s+kB$/m);if(match)return Number.parseInt(match[1],10)*1024}async function readLinuxRssBytes(pid){if(process.platform==="linux")try{const raw=await fs.readFile(`/proc/${pid}/status`,"utf8");return parseLinuxRssStatus(raw)}catch{return}}function parseLinuxCpuStat(raw){const closeParenIndex=raw.lastIndexOf(")");if(closeParenIndex<0)return{};const parts=raw.slice(closeParenIndex+2).trim().split(/\s+/),utimeTicks=Number.parseInt(parts[11],10),stimeTicks=Number.parseInt(parts[12],10);return!Number.isFinite(utimeTicks)||!Number.isFinite(stimeTicks)?{}:{cpu_user_seconds:utimeTicks/PROC_STAT_TICKS_PER_SECOND,cpu_system_seconds:stimeTicks/PROC_STAT_TICKS_PER_SECOND}}async function readLinuxCpuSeconds(pid){if(process.platform!=="linux")return{};try{const raw=await fs.readFile(`/proc/${pid}/stat`,"utf8");return parseLinuxCpuStat(raw)}catch{return{}}}async function buildResourceSnapshot(record){const pid=record.child_pid??record.worker_pid;if(!isPidRunning(pid))return;const rssBytes=await readLinuxRssBytes(pid),cpu=await readLinuxCpuSeconds(pid),startedAtMs=record.started_at?Date.parse(record.started_at):Number.NaN,uptimeSeconds=Number.isFinite(startedAtMs)?Math.max(0,(nowMs()-startedAtMs)/1e3):void 0;return{recorded_at:nowIso(),rss_bytes:rssBytes,cpu_user_seconds:cpu.cpu_user_seconds,cpu_system_seconds:cpu.cpu_system_seconds,uptime_seconds:uptimeSeconds}}function readCount(value){return typeof value=="number"&&Number.isFinite(value)?value:0}function evaluateWorkerResult(kind,payload){if(!payload||typeof payload!="object")return{summary:{passed:0,failed:1,skipped:0},parsedResult:null};const record=payload;if(kind==="test-all"){const totals=record.totals??{};return{summary:{items:typeof totals.items=="number"?totals.items:void 0,linked_tests:typeof totals.linked_tests=="number"?totals.linked_tests:void 0,passed:readCount(totals.passed),failed:readCount(totals.failed),skipped:readCount(totals.skipped),fail_on_skipped_triggered:record.fail_on_skipped_triggered===!0?!0:void 0},parsedResult:payload}}const runResults=Array.isArray(record.run_results)?record.run_results:[];let passed=0,failed=0,skipped=0;for(const entry of runResults){if(!entry||typeof entry!="object")continue;const status=entry.status;if(status==="passed"){passed+=1;continue}if(status==="failed"){failed+=1;continue}skipped+=1}return{summary:{passed,failed,skipped,fail_on_skipped_triggered:record.fail_on_skipped_triggered===!0?!0:void 0},parsedResult:payload}}function parseProgressLine(stderrLine){const line=stderrLine.trim();if(line.length===0)return null;const testAllMatch=line.match(/\[pm test-all\]\s+item\s+(\d+)\/(\d+)\s+(start|end)\s+id=([^\s]+)/i);if(testAllMatch){const itemIndex=Number.parseInt(testAllMatch[1],10),itemTotal=Number.parseInt(testAllMatch[2],10);return{item_index:itemIndex,item_total:itemTotal,item_id:testAllMatch[4],linked_test_index:void 0,linked_test_total:void 0,current_command:void 0,elapsed_ms:void 0,heartbeat_at:nowIso(),phase:testAllMatch[3]?.toLowerCase()==="end"?"finished":"running"}}const linkedTestMatch=line.match(/\[pm test\]\s+linked-test\s+(\d+)\/(\d+)\s+(start|running|end)(?:.*elapsed_ms=(\d+))?/i);if(!linkedTestMatch)return null;const index=Number.parseInt(linkedTestMatch[1],10),total=Number.parseInt(linkedTestMatch[2],10),elapsed=linkedTestMatch[4]?Number.parseInt(linkedTestMatch[4],10):void 0,commandMatch=line.match(/\scommand="((?:\\.|[^"\\])*)"/),currentCommand=commandMatch?commandMatch[1].replaceAll('\\"','"').replaceAll("\\\\","\\"):void 0;return{linked_test_index:index,linked_test_total:total,current_command:currentCommand,elapsed_ms:Number.isFinite(elapsed)?elapsed:void 0,heartbeat_at:nowIso(),phase:linkedTestMatch[3]?.toLowerCase()==="end"?"finished":"running"}}function splitLines(value){return value.split(/\r?\n/).map(entry=>entry.trimEnd()).filter(entry=>entry.length>0)}function tailLines(value,limit){if(limit<=0)return[];const lines=splitLines(value);return lines.length<=limit?lines:lines.slice(lines.length-limit)}async function resolveBackgroundCliEntry(cwd){const configured=process.env.PM_BACKGROUND_CLI_ENTRY?.trim();if(configured&&configured.length>0){const resolvedConfigured=path.resolve(cwd,configured);if(await pathExists(resolvedConfigured))return resolvedConfigured}const distEntry=path.resolve(cwd,"dist","cli.js");if(await pathExists(distEntry))return distEntry;const argvEntry=process.argv[1]?.trim();if(argvEntry&&argvEntry.length>0){const resolvedArgvEntry=path.resolve(cwd,argvEntry);if(await pathExists(resolvedArgvEntry))return resolvedArgvEntry}throw new PmCliError("Unable to resolve a CLI entrypoint for background test runs. Build the project or set PM_BACKGROUND_CLI_ENTRY.",EXIT_CODE.GENERIC_FAILURE)}async function refreshRunIfStale(pmRoot,record){if(!BACKGROUND_RUN_ACTIVE_STATUSES.has(record.status)||isPidRunning(record.worker_pid)||record.finished_at)return record;const next={...record,status:"failed",finished_at:nowIso(),error:record.error??"Background test run worker exited before writing terminal status."};return await writeBackgroundRunRecord(pmRoot,next),next}async function startBackgroundTestRun(options){await ensureBackgroundRunStorage(options.pmRoot);const normalizedArgs=normalizeCommandArgs(options.commandArgs);if(normalizedArgs.length===0)throw new PmCliError("Background test run requires command arguments.",EXIT_CODE.USAGE);const fingerprint=buildBackgroundTestRunFingerprint(options.kind,normalizedArgs,options.pmRoot),existingRuns=await listBackgroundTestRuns(options.pmRoot,{});for(const existing of existingRuns){const refreshed=await refreshRunIfStale(options.pmRoot,existing);if(refreshed.fingerprint===fingerprint&&!(!BACKGROUND_RUN_ACTIVE_STATUSES.has(refreshed.status)||!isPidRunning(refreshed.worker_pid)))return{started:!1,run:{...refreshed,duplicate_of:refreshed.id},duplicate_of:refreshed.id}}const runId=buildRunId(),createdAt=nowIso(),stdoutPath=getTestRunStdoutPath(options.pmRoot,runId),stderrPath=getTestRunStderrPath(options.pmRoot,runId),resultPath=getTestRunResultPath(options.pmRoot,runId);await fs.writeFile(stdoutPath,"","utf8"),await fs.writeFile(stderrPath,"","utf8");const record={id:runId,kind:options.kind,status:"queued",created_at:createdAt,updated_at:createdAt,requested_by:options.requestedBy,fingerprint,command_args:normalizedArgs,command_label:summarizeCommandLabel(normalizedArgs),pm_root:options.pmRoot,global_pm_root:options.globalPmRoot,target_id:options.targetId,status_filter:options.statusFilter,attempt:typeof options.attempt=="number"&&Number.isFinite(options.attempt)&&options.attempt>=1?Math.floor(options.attempt):1,resumed_from:options.resumedFrom,resumed_by:options.resumedBy,stdout_path:stdoutPath,stderr_path:stderrPath,result_path:resultPath,progress:{phase:"queued",message:"Queued for background execution.",heartbeat_at:createdAt}};return await writeBackgroundRunRecord(options.pmRoot,record),{started:!0,run:record}}async function spawnBackgroundTestRunWorker(options){const record=await readBackgroundTestRunRecord(options.pmRoot,options.runId);if(!record)throw new PmCliError(`Background test run ${options.runId} not found`,EXIT_CODE.NOT_FOUND);if(BACKGROUND_RUN_TERMINAL_STATUSES.has(record.status))throw new PmCliError(`Background test run ${record.id} is already terminal (${record.status}).`,EXIT_CODE.CONFLICT);const cliEntry=await resolveBackgroundCliEntry(process.cwd()),args=[];options.noExtensions===!0&&args.push("--no-extensions"),args.push("--path",record.pm_root,"test-runs-worker",record.id);const env={...process.env,PM_PATH:record.pm_root,PM_GLOBAL_PATH:record.global_pm_root,PM_BACKGROUND_TEST_RUN_ID:record.id,PM_BACKGROUND_TEST_RUN_ATTEMPT:String(record.attempt),PM_BACKGROUND_TEST_RUN_RESUMED_FROM:record.resumed_from??"",FORCE_COLOR:"0"},child=spawn(process.execPath,[cliEntry,...args],{cwd:process.cwd(),env,detached:!0,stdio:"ignore",windowsHide:!0});child.unref();const next={...record,status:"queued",worker_pid:child.pid,progress:{phase:"queued",message:"Worker process started.",heartbeat_at:nowIso()}};return await writeBackgroundRunRecord(options.pmRoot,next),next}async function appendFileOrdered(queue,filePath,text){await queue,await fs.appendFile(filePath,text,"utf8")}function resolvePositiveEnvInteger(name,fallback){const parsed=Number.parseInt(process.env[name]??"",10);return Number.isFinite(parsed)&&parsed>0?parsed:fallback}function buildBackgroundWorkerEnv(record){return{...process.env,PM_PATH:record.pm_root,PM_GLOBAL_PATH:record.global_pm_root,FORCE_COLOR:"0"}}function buildBackgroundWorkerChildArgs(record,noExtensions){return noExtensions?["--no-extensions",...record.command_args]:[...record.command_args]}function createBackgroundRunRecordWriteScheduler(pmRoot,record){let writeQueue=Promise.resolve();return{schedule(){writeQueue=writeQueue.then(async()=>{try{await writeBackgroundRunRecord(pmRoot,record)}catch{}})},async flush(){await writeQueue}}}function requestChildSignal(child,signal){try{child.kill(signal)}catch{}}async function requestBackgroundWorkerStop(record,child,state,scheduleRecordWrite){state.stopRequested||(state.stopRequested=!0,record.stop_requested_at=nowIso(),record.progress={...record.progress,phase:"stopping",message:"Stop requested for background run.",heartbeat_at:nowIso()},scheduleRecordWrite(),requestChildSignal(child,"SIGTERM"),setTimeout(()=>requestChildSignal(child,"SIGKILL"),resolvePositiveEnvInteger("PM_BACKGROUND_RUN_FORCE_KILL_DELAY_MS",DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS)).unref?.())}function buildItemBackgroundProgress(line,progressPatch,phase){return{phase,message:line,heartbeat_at:nowIso(),item_index:progressPatch.item_index,item_total:progressPatch.item_total,item_id:progressPatch.item_id,linked_test_index:void 0,linked_test_total:void 0,current_command:void 0,elapsed_ms:void 0}}function buildLinkedTestBackgroundProgress(line,record,progressPatch,phase){return{phase,message:line,heartbeat_at:nowIso(),item_index:progressPatch.item_index??record.progress?.item_index,item_total:progressPatch.item_total??record.progress?.item_total,item_id:progressPatch.item_id??record.progress?.item_id,linked_test_index:progressPatch.linked_test_index,linked_test_total:progressPatch.linked_test_total,current_command:progressPatch.current_command,elapsed_ms:progressPatch.elapsed_ms}}function applyBackgroundWorkerProgressLine(record,line,stopRequested){const progressPatch=parseProgressLine(line);if(!progressPatch)return!1;const phase=record.progress?.phase==="stopping"?"stopping":"running";return record.progress=progressPatch.item_id?buildItemBackgroundProgress(line,progressPatch,phase):buildLinkedTestBackgroundProgress(line,record,progressPatch,phase),progressPatch.phase==="finished"&&!stopRequested&&(record.progress.phase="running"),!0}function parseBackgroundWorkerStdout(stdoutBuffer){if(stdoutBuffer.trim().length===0)return null;try{return JSON.parse(stdoutBuffer)}catch{return null}}function resolveBackgroundWorkerFinalStatus(record,stopRequested){return stopRequested?"stopped":record.exit_code===0&&(record.summary?.failed??0)===0&&record.summary?.fail_on_skipped_triggered!==!0?"passed":"failed"}function buildFinishedBackgroundProgress(record,stopRequested){return{phase:"finished",message:stopRequested?"Background run stopped.":`Background run finished with status=${record.status}.`,heartbeat_at:nowIso(),item_index:record.progress?.item_index,item_total:record.progress?.item_total,item_id:record.progress?.item_id,linked_test_index:record.progress?.linked_test_index,linked_test_total:record.progress?.linked_test_total,current_command:record.progress?.current_command,elapsed_ms:record.progress?.elapsed_ms}}async function writeBackgroundWorkerResult(record,parsedResult,stdoutBuffer){if(parsedResult!==null){await writeFileAtomic(record.result_path,`${JSON.stringify(parsedResult,null,2)}
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7c89b3de-0b7c-529b-a655-87d3e83bd46c")}catch{}})();import fs from"node:fs/promises";import{spawn}from"node:child_process";import{createHash,randomBytes}from"node:crypto";import path from"node:path";import{ensureDir,pathExists,readFileIfExists,writeFileAtomic}from"../fs/fs-utils.js";import{PmCliError}from"../shared/errors.js";import{EXIT_CODE}from"../shared/constants.js";import{nowIso}from"../shared/time.js";import{getTestRunRecordPath,getTestRunResultPath,getTestRunStderrPath,getTestRunStdoutPath,getTestRunsPath,getTestRunsRecordsPath,getTestRunsResultsPath,getTestRunsStderrPath,getTestRunsStdoutPath}from"../store/paths.js";const BACKGROUND_RUN_ACTIVE_STATUSES=new Set(["queued","running"]),BACKGROUND_RUN_TERMINAL_STATUSES=new Set(["passed","failed","stopped","canceled"]),DEFAULT_BACKGROUND_RUN_RESOURCE_SNAPSHOT_INTERVAL_MS=3e3,DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS=3e3,DEFAULT_BACKGROUND_RUN_HEARTBEAT_STALE_MS=3e4,DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES=100,PROC_STAT_TICKS_PER_SECOND=100;function nowMs(){return Date.now()}function normalizeCommandArgs(args){return args.map(entry=>entry.trim()).filter(entry=>entry.length>0)}function summarizeCommandLabel(args){const joined=args.join(" ").replaceAll(/\s+/g," ").trim();return joined.length<=180?joined:`${joined.slice(0,177)}...`}function buildRunId(){const timePart=Date.now().toString(36),randomPart=randomBytes(3).toString("hex");return`tr-${timePart}-${randomPart}`}function buildBackgroundTestRunFingerprint(kind,commandArgs,pmRoot){const payload={kind,command:normalizeCommandArgs(commandArgs),pm_root:path.resolve(pmRoot)};return createHash("sha256").update(JSON.stringify(payload)).digest("hex")}function isPidRunning(pid){if(!Number.isInteger(pid)||!pid||pid<=0)return!1;try{return process.kill(pid,0),!0}catch(error){return(typeof error=="object"&&error!==null&&"code"in error?error.code:void 0)==="EPERM"}}async function ensureBackgroundRunStorage(pmRoot){await ensureDir(getTestRunsPath(pmRoot)),await ensureDir(getTestRunsRecordsPath(pmRoot)),await ensureDir(getTestRunsStdoutPath(pmRoot)),await ensureDir(getTestRunsStderrPath(pmRoot)),await ensureDir(getTestRunsResultsPath(pmRoot))}async function parseBackgroundRunRecord(raw,recordPath){try{const parsed=JSON.parse(raw);if(!parsed||typeof parsed!="object"||typeof parsed.id!="string")throw new Error("invalid run record payload");return parsed}catch(error){throw new PmCliError(`Failed to parse background test run record at ${recordPath}: ${error instanceof Error?error.message:String(error)}`,EXIT_CODE.GENERIC_FAILURE)}}async function writeBackgroundRunRecord(pmRoot,record){const next={...record,updated_at:nowIso()};await writeFileAtomic(getTestRunRecordPath(pmRoot,record.id),`${JSON.stringify(next,null,2)}
+`)}async function readBackgroundTestRunRecord(pmRoot,runId){const recordPath=getTestRunRecordPath(pmRoot,runId),raw=await readFileIfExists(recordPath);return raw?parseBackgroundRunRecord(raw,recordPath):null}async function listBackgroundRunRecordPaths(pmRoot){const recordsRoot=getTestRunsRecordsPath(pmRoot);return await pathExists(recordsRoot)?(await fs.readdir(recordsRoot,{withFileTypes:!0})).filter(entry=>entry.isFile()&&entry.name.endsWith(".json")).map(entry=>path.join(recordsRoot,entry.name)).sort((left,right)=>right.localeCompare(left)):[]}function parseLinuxRssStatus(raw){const match=raw.match(/^VmRSS:\s+(\d+)\s+kB$/m);if(match)return Number.parseInt(match[1],10)*1024}async function readLinuxRssBytes(pid){if(process.platform==="linux")try{const raw=await fs.readFile(`/proc/${pid}/status`,"utf8");return parseLinuxRssStatus(raw)}catch{return}}function parseLinuxCpuStat(raw){const closeParenIndex=raw.lastIndexOf(")");if(closeParenIndex<0)return{};const parts=raw.slice(closeParenIndex+2).trim().split(/\s+/),utimeTicks=Number.parseInt(parts[11],10),stimeTicks=Number.parseInt(parts[12],10);return!Number.isFinite(utimeTicks)||!Number.isFinite(stimeTicks)?{}:{cpu_user_seconds:utimeTicks/PROC_STAT_TICKS_PER_SECOND,cpu_system_seconds:stimeTicks/PROC_STAT_TICKS_PER_SECOND}}async function readLinuxCpuSeconds(pid){if(process.platform!=="linux")return{};try{const raw=await fs.readFile(`/proc/${pid}/stat`,"utf8");return parseLinuxCpuStat(raw)}catch{return{}}}async function buildResourceSnapshot(record){const pid=record.child_pid??record.worker_pid;if(!isPidRunning(pid))return;const rssBytes=await readLinuxRssBytes(pid),cpu=await readLinuxCpuSeconds(pid),startedAtMs=record.started_at?Date.parse(record.started_at):Number.NaN,uptimeSeconds=Number.isFinite(startedAtMs)?Math.max(0,(nowMs()-startedAtMs)/1e3):void 0;return{recorded_at:nowIso(),rss_bytes:rssBytes,cpu_user_seconds:cpu.cpu_user_seconds,cpu_system_seconds:cpu.cpu_system_seconds,uptime_seconds:uptimeSeconds}}function readCount(value){return typeof value=="number"&&Number.isFinite(value)?value:0}function evaluateWorkerResult(kind,payload){if(!payload||typeof payload!="object")return{summary:{passed:0,failed:1,skipped:0},parsedResult:null};const record=payload;if(kind==="test-all"){const totals=record.totals??{};return{summary:{items:typeof totals.items=="number"?totals.items:void 0,linked_tests:typeof totals.linked_tests=="number"?totals.linked_tests:void 0,passed:readCount(totals.passed),failed:readCount(totals.failed),skipped:readCount(totals.skipped),fail_on_skipped_triggered:record.fail_on_skipped_triggered===!0?!0:void 0},parsedResult:payload}}const runResults=Array.isArray(record.run_results)?record.run_results:[];let passed=0,failed=0,skipped=0;for(const entry of runResults){if(!entry||typeof entry!="object")continue;const status=entry.status;if(status==="passed"){passed+=1;continue}if(status==="failed"||status==="refused"){failed+=1;continue}skipped+=1}return{summary:{passed,failed,skipped,fail_on_skipped_triggered:record.fail_on_skipped_triggered===!0?!0:void 0},parsedResult:payload}}function parseProgressLine(stderrLine){const line=stderrLine.trim();if(line.length===0)return null;const testAllMatch=line.match(/\[pm test-all\]\s+item\s+(\d+)\/(\d+)\s+(start|end)\s+id=([^\s]+)/i);if(testAllMatch){const itemIndex=Number.parseInt(testAllMatch[1],10),itemTotal=Number.parseInt(testAllMatch[2],10);return{item_index:itemIndex,item_total:itemTotal,item_id:testAllMatch[4],linked_test_index:void 0,linked_test_total:void 0,current_command:void 0,elapsed_ms:void 0,heartbeat_at:nowIso(),phase:testAllMatch[3]?.toLowerCase()==="end"?"finished":"running"}}const linkedTestMatch=line.match(/\[pm test\]\s+linked-test\s+(\d+)\/(\d+)\s+(start|running|end)(?:.*elapsed_ms=(\d+))?/i);if(!linkedTestMatch)return null;const index=Number.parseInt(linkedTestMatch[1],10),total=Number.parseInt(linkedTestMatch[2],10),elapsed=linkedTestMatch[4]?Number.parseInt(linkedTestMatch[4],10):void 0,commandMatch=line.match(/\scommand="((?:\\.|[^"\\])*)"/),currentCommand=commandMatch?commandMatch[1].replaceAll('\\"','"').replaceAll("\\\\","\\"):void 0;return{linked_test_index:index,linked_test_total:total,current_command:currentCommand,elapsed_ms:Number.isFinite(elapsed)?elapsed:void 0,heartbeat_at:nowIso(),phase:linkedTestMatch[3]?.toLowerCase()==="end"?"finished":"running"}}function splitLines(value){return value.split(/\r?\n/).map(entry=>entry.trimEnd()).filter(entry=>entry.length>0)}function tailLines(value,limit){if(limit<=0)return[];const lines=splitLines(value);return lines.length<=limit?lines:lines.slice(lines.length-limit)}async function resolveBackgroundCliEntry(cwd){const configured=process.env.PM_BACKGROUND_CLI_ENTRY?.trim();if(configured&&configured.length>0){const resolvedConfigured=path.resolve(cwd,configured);if(await pathExists(resolvedConfigured))return resolvedConfigured}const distEntry=path.resolve(cwd,"dist","cli.js");if(await pathExists(distEntry))return distEntry;const argvEntry=process.argv[1]?.trim();if(argvEntry&&argvEntry.length>0){const resolvedArgvEntry=path.resolve(cwd,argvEntry);if(await pathExists(resolvedArgvEntry))return resolvedArgvEntry}throw new PmCliError("Unable to resolve a CLI entrypoint for background test runs. Build the project or set PM_BACKGROUND_CLI_ENTRY.",EXIT_CODE.GENERIC_FAILURE)}async function refreshRunIfStale(pmRoot,record){if(!BACKGROUND_RUN_ACTIVE_STATUSES.has(record.status)||isPidRunning(record.worker_pid)||record.finished_at)return record;const next={...record,status:"failed",finished_at:nowIso(),error:record.error??"Background test run worker exited before writing terminal status."};return await writeBackgroundRunRecord(pmRoot,next),next}async function startBackgroundTestRun(options){await ensureBackgroundRunStorage(options.pmRoot);const normalizedArgs=normalizeCommandArgs(options.commandArgs);if(normalizedArgs.length===0)throw new PmCliError("Background test run requires command arguments.",EXIT_CODE.USAGE);const fingerprint=buildBackgroundTestRunFingerprint(options.kind,normalizedArgs,options.pmRoot),existingRuns=await listBackgroundTestRuns(options.pmRoot,{});for(const existing of existingRuns){const refreshed=await refreshRunIfStale(options.pmRoot,existing);if(refreshed.fingerprint===fingerprint&&!(!BACKGROUND_RUN_ACTIVE_STATUSES.has(refreshed.status)||!isPidRunning(refreshed.worker_pid)))return{started:!1,run:{...refreshed,duplicate_of:refreshed.id},duplicate_of:refreshed.id}}const runId=buildRunId(),createdAt=nowIso(),stdoutPath=getTestRunStdoutPath(options.pmRoot,runId),stderrPath=getTestRunStderrPath(options.pmRoot,runId),resultPath=getTestRunResultPath(options.pmRoot,runId);await fs.writeFile(stdoutPath,"","utf8"),await fs.writeFile(stderrPath,"","utf8");const record={id:runId,kind:options.kind,status:"queued",created_at:createdAt,updated_at:createdAt,requested_by:options.requestedBy,fingerprint,command_args:normalizedArgs,command_label:summarizeCommandLabel(normalizedArgs),pm_root:options.pmRoot,global_pm_root:options.globalPmRoot,target_id:options.targetId,status_filter:options.statusFilter,attempt:typeof options.attempt=="number"&&Number.isFinite(options.attempt)&&options.attempt>=1?Math.floor(options.attempt):1,resumed_from:options.resumedFrom,resumed_by:options.resumedBy,stdout_path:stdoutPath,stderr_path:stderrPath,result_path:resultPath,progress:{phase:"queued",message:"Queued for background execution.",heartbeat_at:createdAt}};return await writeBackgroundRunRecord(options.pmRoot,record),{started:!0,run:record}}async function spawnBackgroundTestRunWorker(options){const record=await readBackgroundTestRunRecord(options.pmRoot,options.runId);if(!record)throw new PmCliError(`Background test run ${options.runId} not found`,EXIT_CODE.NOT_FOUND);if(BACKGROUND_RUN_TERMINAL_STATUSES.has(record.status))throw new PmCliError(`Background test run ${record.id} is already terminal (${record.status}).`,EXIT_CODE.CONFLICT);const cliEntry=await resolveBackgroundCliEntry(process.cwd()),args=[];options.noExtensions===!0&&args.push("--no-extensions"),args.push("--path",record.pm_root,"test-runs-worker",record.id);const env={...process.env,PM_PATH:record.pm_root,PM_GLOBAL_PATH:record.global_pm_root,PM_BACKGROUND_TEST_RUN_ID:record.id,PM_BACKGROUND_TEST_RUN_ATTEMPT:String(record.attempt),PM_BACKGROUND_TEST_RUN_RESUMED_FROM:record.resumed_from??"",FORCE_COLOR:"0"},child=spawn(process.execPath,[cliEntry,...args],{cwd:process.cwd(),env,detached:!0,stdio:"ignore",windowsHide:!0});child.unref();const next={...record,status:"queued",worker_pid:child.pid,progress:{phase:"queued",message:"Worker process started.",heartbeat_at:nowIso()}};return await writeBackgroundRunRecord(options.pmRoot,next),next}async function appendFileOrdered(queue,filePath,text){await queue,await fs.appendFile(filePath,text,"utf8")}function resolvePositiveEnvInteger(name,fallback){const parsed=Number.parseInt(process.env[name]??"",10);return Number.isFinite(parsed)&&parsed>0?parsed:fallback}function buildBackgroundWorkerEnv(record){return{...process.env,PM_PATH:record.pm_root,PM_GLOBAL_PATH:record.global_pm_root,FORCE_COLOR:"0"}}function buildBackgroundWorkerChildArgs(record,noExtensions){return noExtensions?["--no-extensions",...record.command_args]:[...record.command_args]}function createBackgroundRunRecordWriteScheduler(pmRoot,record){let writeQueue=Promise.resolve();return{schedule(){writeQueue=writeQueue.then(async()=>{try{await writeBackgroundRunRecord(pmRoot,record)}catch{}})},async flush(){await writeQueue}}}function requestChildSignal(child,signal){try{child.kill(signal)}catch{}}async function requestBackgroundWorkerStop(record,child,state,scheduleRecordWrite){state.stopRequested||(state.stopRequested=!0,record.stop_requested_at=nowIso(),record.progress={...record.progress,phase:"stopping",message:"Stop requested for background run.",heartbeat_at:nowIso()},scheduleRecordWrite(),requestChildSignal(child,"SIGTERM"),setTimeout(()=>requestChildSignal(child,"SIGKILL"),resolvePositiveEnvInteger("PM_BACKGROUND_RUN_FORCE_KILL_DELAY_MS",DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS)).unref?.())}function buildItemBackgroundProgress(line,progressPatch,phase){return{phase,message:line,heartbeat_at:nowIso(),item_index:progressPatch.item_index,item_total:progressPatch.item_total,item_id:progressPatch.item_id,linked_test_index:void 0,linked_test_total:void 0,current_command:void 0,elapsed_ms:void 0}}function buildLinkedTestBackgroundProgress(line,record,progressPatch,phase){return{phase,message:line,heartbeat_at:nowIso(),item_index:progressPatch.item_index??record.progress?.item_index,item_total:progressPatch.item_total??record.progress?.item_total,item_id:progressPatch.item_id??record.progress?.item_id,linked_test_index:progressPatch.linked_test_index,linked_test_total:progressPatch.linked_test_total,current_command:progressPatch.current_command,elapsed_ms:progressPatch.elapsed_ms}}function applyBackgroundWorkerProgressLine(record,line,stopRequested){const progressPatch=parseProgressLine(line);if(!progressPatch)return!1;const phase=record.progress?.phase==="stopping"?"stopping":"running";return record.progress=progressPatch.item_id?buildItemBackgroundProgress(line,progressPatch,phase):buildLinkedTestBackgroundProgress(line,record,progressPatch,phase),progressPatch.phase==="finished"&&!stopRequested&&(record.progress.phase="running"),!0}function parseBackgroundWorkerStdout(stdoutBuffer){if(stdoutBuffer.trim().length===0)return null;try{return JSON.parse(stdoutBuffer)}catch{return null}}function resolveBackgroundWorkerFinalStatus(record,stopRequested){return stopRequested?"stopped":record.exit_code===0&&(record.summary?.failed??0)===0&&record.summary?.fail_on_skipped_triggered!==!0?"passed":"failed"}function buildFinishedBackgroundProgress(record,stopRequested){return{phase:"finished",message:stopRequested?"Background run stopped.":`Background run finished with status=${record.status}.`,heartbeat_at:nowIso(),item_index:record.progress?.item_index,item_total:record.progress?.item_total,item_id:record.progress?.item_id,linked_test_index:record.progress?.linked_test_index,linked_test_total:record.progress?.linked_test_total,current_command:record.progress?.current_command,elapsed_ms:record.progress?.elapsed_ms}}async function writeBackgroundWorkerResult(record,parsedResult,stdoutBuffer){if(parsedResult!==null){await writeFileAtomic(record.result_path,`${JSON.stringify(parsedResult,null,2)}
 `);return}await writeFileAtomic(record.result_path,`${JSON.stringify({parse_error:"Background run output was not valid JSON.",stdout_excerpt:tailLines(stdoutBuffer,DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES)},null,2)}
 `)}async function runBackgroundTestRunWorker(pmRoot,runId,noExtensions=!1){const loaded=await readBackgroundTestRunRecord(pmRoot,runId);if(!loaded)throw new PmCliError(`Background test run ${runId} not found`,EXIT_CODE.NOT_FOUND);const record={...loaded,status:"running",started_at:loaded.started_at??nowIso(),worker_pid:process.pid,progress:{phase:"running",message:"Worker started.",heartbeat_at:nowIso()}},cliEntry=await resolveBackgroundCliEntry(process.cwd()),env=buildBackgroundWorkerEnv(record);await writeBackgroundRunRecord(pmRoot,record);const childArgs=buildBackgroundWorkerChildArgs(record,noExtensions),child=spawn(process.execPath,[cliEntry,...childArgs],{cwd:process.cwd(),env,detached:!1,stdio:["ignore","pipe","pipe"],windowsHide:!0});record.child_pid=child.pid;const recordWriteScheduler=createBackgroundRunRecordWriteScheduler(pmRoot,record),scheduleRecordWrite=recordWriteScheduler.schedule;let stdoutWriteQueue=Promise.resolve(),stderrWriteQueue=Promise.resolve(),stdoutBuffer="",stderrBuffer="";const stopState={stopRequested:!1},onSignal=()=>{requestBackgroundWorkerStop(record,child,stopState,scheduleRecordWrite)};process.on("SIGTERM",onSignal),process.on("SIGINT",onSignal);const resourceTimer=setInterval(()=>{(async()=>(record.resource=await buildResourceSnapshot(record),record.progress.heartbeat_at=nowIso(),scheduleRecordWrite()))()},resolvePositiveEnvInteger("PM_BACKGROUND_RUN_RESOURCE_INTERVAL_MS",DEFAULT_BACKGROUND_RUN_RESOURCE_SNAPSHOT_INTERVAL_MS));resourceTimer.unref?.(),child.stdout?.on("data",chunk=>{const text=chunk.toString("utf8");stdoutBuffer+=text,stdoutWriteQueue=appendFileOrdered(stdoutWriteQueue,record.stdout_path,text)}),child.stderr?.on("data",chunk=>{const text=chunk.toString("utf8");stderrWriteQueue=appendFileOrdered(stderrWriteQueue,record.stderr_path,text),stderrBuffer+=text;const parts=stderrBuffer.split(/\r?\n/);stderrBuffer=parts.pop();let progressChanged=!1;for(const part of parts){const line=part.trimEnd();line.length>0&&applyBackgroundWorkerProgressLine(record,line,stopState.stopRequested)&&(progressChanged=!0)}progressChanged&&scheduleRecordWrite()});let exitCode=null,signal=null;try{({code:exitCode,signal}=await new Promise(resolve=>{child.on("close",(code,closeSignal)=>{resolve({code,signal:closeSignal})})}))}finally{clearInterval(resourceTimer),process.off("SIGTERM",onSignal),process.off("SIGINT",onSignal)}await stdoutWriteQueue,await stderrWriteQueue;const trailingStderrLine=stderrBuffer.trimEnd();trailingStderrLine.length>0&&applyBackgroundWorkerProgressLine(record,trailingStderrLine,stopState.stopRequested)&&scheduleRecordWrite(),stderrBuffer="";const parsedResult=parseBackgroundWorkerStdout(stdoutBuffer),evaluated=evaluateWorkerResult(record.kind,parsedResult);return record.summary=evaluated.summary,record.exit_code=typeof exitCode=="number"?exitCode:void 0,record.signal=signal??void 0,record.finished_at=nowIso(),record.status=resolveBackgroundWorkerFinalStatus(record,stopState.stopRequested),record.progress=buildFinishedBackgroundProgress(record,stopState.stopRequested),record.resource=await buildResourceSnapshot(record),await writeBackgroundWorkerResult(record,parsedResult,stdoutBuffer),await writeBackgroundRunRecord(pmRoot,record),await recordWriteScheduler.flush(),record}async function listBackgroundTestRuns(pmRoot,options){const recordPaths=await listBackgroundRunRecordPaths(pmRoot),runs=[];for(const recordPath of recordPaths){const raw=await readFileIfExists(recordPath);if(!raw)continue;const parsed=await parseBackgroundRunRecord(raw,recordPath);runs.push(parsed)}const refreshed=[];for(const run of runs)refreshed.push(await refreshRunIfStale(pmRoot,run));const sorted=(options.status?refreshed.filter(entry=>entry.status===options.status):refreshed).sort((left,right)=>{const byUpdated=Date.parse(right.updated_at)-Date.parse(left.updated_at);return Number.isFinite(byUpdated)&&byUpdated!==0?byUpdated:right.id.localeCompare(left.id)}),limit=typeof options.limit=="number"&&options.limit>=0?options.limit:void 0;return limit===void 0?sorted:sorted.slice(0,limit)}async function getBackgroundTestRunStatus(pmRoot,runId){const loaded=await readBackgroundTestRunRecord(pmRoot,runId);if(!loaded)throw new PmCliError(`Background test run ${runId} not found`,EXIT_CODE.NOT_FOUND);const refreshed=await refreshRunIfStale(pmRoot,loaded),workerAlive=isPidRunning(refreshed.worker_pid),childAlive=isPidRunning(refreshed.child_pid);refreshed.status==="running"&&!childAlive&&!refreshed.finished_at&&!workerAlive&&(refreshed.status="failed",refreshed.finished_at=nowIso(),refreshed.error=refreshed.error??"Background run process exited unexpectedly.",await writeBackgroundRunRecord(pmRoot,refreshed)),refreshed.status==="running"&&(refreshed.resource=await buildResourceSnapshot(refreshed),await writeBackgroundRunRecord(pmRoot,refreshed));const heartbeatAt=refreshed.progress?.heartbeat_at,heartbeatAtMs=heartbeatAt?Date.parse(heartbeatAt):Number.NaN,lagMs=Number.isFinite(heartbeatAtMs)?Math.max(0,nowMs()-heartbeatAtMs):void 0,staleMs=Number.parseInt(process.env.PM_BACKGROUND_RUN_HEARTBEAT_STALE_MS??"",10),staleThresholdMs=Number.isFinite(staleMs)&&staleMs>0?staleMs:DEFAULT_BACKGROUND_RUN_HEARTBEAT_STALE_MS,healthState=refreshed.status==="running"?lagMs!==void 0&&lagMs>staleThresholdMs?"stale":"healthy":"inactive";return{run:refreshed,health:{state:healthState,last_heartbeat_at:heartbeatAt,heartbeat_lag_ms:lagMs,worker_alive:workerAlive,child_alive:childAlive}}}function sendBackgroundRunStopSignal(record,force){const signal=force?"SIGKILL":"SIGTERM";if(!isPidRunning(record.worker_pid)||!record.worker_pid)return"none";try{return process.kill(record.worker_pid,signal),signal}catch{return"none"}}function buildStoppingBackgroundProgress(record,signalSent){return{phase:"stopping",message:signalSent==="none"?"Run marked stopped.":`Stop requested via ${signalSent}.`,heartbeat_at:nowIso(),item_index:record.progress?.item_index,item_total:record.progress?.item_total,item_id:record.progress?.item_id,linked_test_index:record.progress?.linked_test_index,linked_test_total:record.progress?.linked_test_total,current_command:record.progress?.current_command,elapsed_ms:record.progress?.elapsed_ms}}async function stopBackgroundTestRun(pmRoot,runId,force=!1){const loaded=await readBackgroundTestRunRecord(pmRoot,runId);if(!loaded)throw new PmCliError(`Background test run ${runId} not found`,EXIT_CODE.NOT_FOUND);const refreshed=await refreshRunIfStale(pmRoot,loaded);if(BACKGROUND_RUN_TERMINAL_STATUSES.has(refreshed.status))return{run:refreshed,signal_sent:"none"};const signalSent=sendBackgroundRunStopSignal(refreshed,force);return signalSent==="none"&&(refreshed.status="stopped",refreshed.finished_at=refreshed.finished_at??nowIso()),refreshed.stop_requested_at=nowIso(),refreshed.progress=buildStoppingBackgroundProgress(refreshed,signalSent),await writeBackgroundRunRecord(pmRoot,refreshed),{run:refreshed,signal_sent:signalSent}}async function resumeBackgroundTestRun(pmRoot,runId,requestedBy,noExtensions=!1){const loaded=await readBackgroundTestRunRecord(pmRoot,runId);if(!loaded)throw new PmCliError(`Background test run ${runId} not found`,EXIT_CODE.NOT_FOUND);const refreshed=await refreshRunIfStale(pmRoot,loaded);if(!BACKGROUND_RUN_TERMINAL_STATUSES.has(refreshed.status))throw new PmCliError(`Background test run ${runId} is not terminal and cannot be resumed.`,EXIT_CODE.CONFLICT);const started=await startBackgroundTestRun({pmRoot:refreshed.pm_root,globalPmRoot:refreshed.global_pm_root,kind:refreshed.kind,commandArgs:refreshed.command_args,requestedBy,targetId:refreshed.target_id,statusFilter:refreshed.status_filter,resumedFrom:refreshed.id,resumedBy:requestedBy,attempt:refreshed.attempt+1});if(!started.started)return started.run;const spawned=await spawnBackgroundTestRunWorker({pmRoot,runId:started.run.id,noExtensions}),prior={...refreshed,resumed_by:spawned.id};return await writeBackgroundRunRecord(pmRoot,prior),spawned}async function readBackgroundTestRunLogs(pmRoot,runId,stream,tail){const loaded=await readBackgroundTestRunRecord(pmRoot,runId);if(!loaded)throw new PmCliError(`Background test run ${runId} not found`,EXIT_CODE.NOT_FOUND);const resolvedTail=typeof tail=="number"&&Number.isFinite(tail)&&tail>=0?Math.floor(tail):DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES,stdoutRaw=stream==="stdout"||stream==="both"?await readFileIfExists(loaded.stdout_path)??"":"",stderrRaw=stream==="stderr"||stream==="both"?await readFileIfExists(loaded.stderr_path)??"":"";return{run:loaded,stream,tail:resolvedTail,stdout:stream==="stdout"||stream==="both"?tailLines(stdoutRaw,resolvedTail):[],stderr:stream==="stderr"||stream==="both"?tailLines(stderrRaw,resolvedTail):[]}}const _testOnly={buildResourceSnapshot,evaluateWorkerResult,isPidRunning,parseLinuxCpuStat,parseLinuxRssStatus,parseProgressLine,readLinuxCpuSeconds,readLinuxRssBytes,refreshRunIfStale,splitLines,tailLines};export{_testOnly,buildBackgroundTestRunFingerprint,getBackgroundTestRunStatus,listBackgroundTestRuns,readBackgroundTestRunLogs,readBackgroundTestRunRecord,resumeBackgroundTestRun,runBackgroundTestRunWorker,spawnBackgroundTestRunWorker,startBackgroundTestRun,stopBackgroundTestRun};
 //# sourceMappingURL=background-runs.js.map

package/dist/core/test/item-test-run-tracking.d.ts

@@ -3,10 +3,10 @@ import type { ItemTestRunSummary, PmSettings } from "../../types/index.js";
 export declare function buildTrackedTestRunHistory(entries: ItemTestRunSummary[]): ItemTestRunSummary[];
 /** Implements append tracked test run summary for the public runtime surface of this module. */
 export declare function appendTrackedTestRunSummary(options: {
-    pmRoot: string;
-    settings: PmSettings;
-    itemId: string;
-    author: string;
-    entry: ItemTestRunSummary;
-    message?: string;
+pmRoot: string;
+settings: PmSettings;
+itemId: string;
+author: string;
+entry: ItemTestRunSummary;
+message?: string;
 }): Promise<void>;

package/dist/core/test/run-selectors.d.ts

@@ -10,27 +10,27 @@ import type { LinkedTest } from "../../types.js";
 export type LinkedTestSelectorKind = "match" | "only-index" | "only-last";
 /** Documents the linked test run selector payload exchanged by command, SDK, and package integrations. */
 export interface LinkedTestRunSelector {
-    /** Value that configures or reports match for this contract. */
-    match?: string;
-    /** Value that configures or reports only index for this contract. */
-    onlyIndex?: number;
-    /** Value that configures or reports only last for this contract. */
-    onlyLast?: boolean;
+/** Value that configures or reports match for this contract. */
+match?: string;
+/** Value that configures or reports only index for this contract. */
+onlyIndex?: number;
+/** Value that configures or reports only last for this contract. */
+onlyLast?: boolean;
 }
 /** Documents the linked test run selection payload exchanged by command, SDK, and package integrations. */
 export interface LinkedTestRunSelection {
-    /** Value that configures or reports selector for this contract. */
-    selector: LinkedTestSelectorKind | null;
-    /** Value that configures or reports requested for this contract. */
-    requested: string | null;
-    /** Value that configures or reports selected for this contract. */
-    selected: LinkedTest[];
-    /** 1-based positions of selected entries in the original `--list` order. */
-    selected_indexes: number[];
-    /** Number of selected entries represented by this result. */
-    selected_count: number;
-    /** Number of skipped entries represented by this result. */
-    skipped_count: number;
+/** Value that configures or reports selector for this contract. */
+selector: LinkedTestSelectorKind | null;
+/** Value that configures or reports requested for this contract. */
+requested: string | null;
+/** Value that configures or reports selected for this contract. */
+selected: LinkedTest[];
+/** 1-based positions of selected entries in the original `--list` order. */
+selected_indexes: number[];
+/** Number of selected entries represented by this result. */
+selected_count: number;
+/** Number of skipped entries represented by this result. */
+skipped_count: number;
 }
 /** Implements parse only index value for the public runtime surface of this module. */
 export declare function parseOnlyIndexValue(raw: string | number, optionName?: string): number;

package/dist/core/validate/fix-planning.d.ts

@@ -27,77 +27,77 @@ export declare const DEFAULT_GRANTED_FIX_SCOPES: readonly ValidateFixScope[];
 export declare const SUPPORTED_FIX_SCOPES: readonly ValidateFixScope[];
 /** Documents the validate fix record payload exchanged by command, SDK, and package integrations. */
 export interface ValidateFixRecord {
-    /** Item the fix targets. */
-    item_id: string;
-    /** Validate check the finding came from. */
-    check: ValidateFixCheck;
-    /** Item-metadata field (or link list) the fix changes. */
-    field: string;
-    /** Declarative fix kind the applier dispatches on. */
-    kind: ValidateFixKind;
-    /** Equivalent standalone `pm` command for the fix. */
-    command: string;
-    /** New value for set-field fixes. */
-    value?: string;
-    /** Stale link path for prune fixes. */
-    path?: string;
-    /** Target parent id for reparent fixes. */
-    parent_id?: string;
-    /** Fix scope the `--fix-scope` allowlist must grant for the fix to be applied. Every `--auto-fix` record carries one (the granted default is metadata+resolution; lifecycle must be named explicitly). Absent only on `--prune-missing` records, which are governed by their own flag. */
-    gate?: ValidateFixScope;
+/** Item the fix targets. */
+item_id: string;
+/** Validate check the finding came from. */
+check: ValidateFixCheck;
+/** Item-metadata field (or link list) the fix changes. */
+field: string;
+/** Declarative fix kind the applier dispatches on. */
+kind: ValidateFixKind;
+/** Equivalent standalone `pm` command for the fix. */
+command: string;
+/** New value for set-field fixes. */
+value?: string;
+/** Stale link path for prune fixes. */
+path?: string;
+/** Target parent id for reparent fixes. */
+parent_id?: string;
+/** Fix scope the `--fix-scope` allowlist must grant for the fix to be applied. Every `--auto-fix` record carries one (the granted default is metadata+resolution; lifecycle must be named explicitly). Absent only on `--prune-missing` records, which are governed by their own flag. */
+gate?: ValidateFixScope;
 }
 /** Documents the resolution backfill row payload exchanged by command, SDK, and package integrations. */
 export interface ResolutionBackfillRow {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Resolution-check missing field keys for this closed item. */
-    missing_fields: readonly string[];
-    /** The item's close_reason, when present (preferred derivation source). */
-    close_reason?: string;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Resolution-check missing field keys for this closed item. */
+missing_fields: readonly string[];
+/** The item's close_reason, when present (preferred derivation source). */
+close_reason?: string;
 }
 /** Plan resolution backfills for closed items flagged by the resolution check. Only the `resolution` field is mechanical enough to auto-fix: it derives from the item's own `close_reason` when present and falls back to the `"completed"` default. `expected_result` / `actual_result` stay hint-only — no deterministic source text exists for them. */
 export declare function planResolutionBackfillFixes(rows: readonly ResolutionBackfillRow[]): ValidateFixRecord[];
 /** Documents the close reason backfill row payload exchanged by command, SDK, and package integrations. */
 export interface CloseReasonBackfillRow {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** The item's resolution, when present (the only derivation source). */
-    resolution?: string;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** The item's resolution, when present (the only derivation source). */
+resolution?: string;
 }
 /** Plan close_reason backfills for closed items flagged by the metadata check. Only derivable when the item already carries a resolution; items missing both stay hint-only (any synthesized reason would be fabricated, not derived). */
 export declare function planCloseReasonBackfillFixes(rows: readonly CloseReasonBackfillRow[]): ValidateFixRecord[];
 /** Documents the estimate backfill row payload exchanged by command, SDK, and package integrations. */
 export interface EstimateBackfillRow {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Item type, used to resolve the per-type default estimate. */
-    type?: string;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Item type, used to resolve the per-type default estimate. */
+type?: string;
 }
 /** Plan estimate backfills for items flagged by the metadata check as missing `estimated_minutes` (GH-212). The value is a config-driven per-type default (overrides > built-in map > fallback), never a derived fact — so these fixes carry `gate: "estimates"`, an opt-in scope that is NOT granted by default. `overrides` is the already-normalized `validation.estimate_defaults_by_type` map; pass `undefined`/`{}` to use the built-in defaults. */
 export declare function planEstimateBackfillFixes(rows: readonly EstimateBackfillRow[], overrides?: Readonly<Record<string, number>>): ValidateFixRecord[];
 /** Documents the terminal parent fix row payload exchanged by command, SDK, and package integrations. */
 export interface TerminalParentFixRow {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports parent id for this contract. */
-    parent_id: string;
-    /** The terminal parent's own parent, when one exists. */
-    grandparent_id?: string;
-    /** True when the grandparent exists and is NOT terminal (safe reparent target). */
-    grandparent_active?: boolean;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports parent id for this contract. */
+parent_id: string;
+/** The terminal parent's own parent, when one exists. */
+grandparent_id?: string;
+/** True when the grandparent exists and is NOT terminal (safe reparent target). */
+grandparent_active?: boolean;
 }
 /** Plan lifecycle fixes for active items whose parent is terminal (pm-8jss / GH-168). When the terminal parent has an active grandparent, the child is reparented one level up (it stays inside the same hierarchy); otherwise the parent link is cleared so the item surfaces as unparented active work. Either way the item itself is never closed or mutated beyond `parent` — and every fix carries `gate: "lifecycle"` so it is only applied under an explicit `--fix-scope lifecycle`. */
 export declare function planTerminalParentFixes(rows: readonly TerminalParentFixRow[]): ValidateFixRecord[];
 /** Documents the stale link prune row payload exchanged by command, SDK, and package integrations. */
 export interface StaleLinkPruneRow {
-    /** Value that configures or reports item id for this contract. */
-    item_id: string;
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports link kind for this contract. */
-    link_kind: "files" | "docs";
-    /** Value that configures or reports classification for this contract. */
-    classification: "moved" | "deleted" | "malformed";
+/** Value that configures or reports item id for this contract. */
+item_id: string;
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports link kind for this contract. */
+link_kind: "files" | "docs";
+/** Value that configures or reports classification for this contract. */
+classification: "moved" | "deleted" | "malformed";
 }
 /** Plan link prunes for `--prune-missing` (pm-0v2m / GH-184). Only links whose stale path classified as `deleted` are pruned; `moved` links keep their relink candidates in the files-check details instead of being dropped, so recoverable link information is never destroyed. Link removal only — real files are never touched. */
 export declare function planStaleLinkPruneFixes(rows: readonly StaleLinkPruneRow[]): ValidateFixRecord[];
@@ -105,8 +105,8 @@ export declare function planStaleLinkPruneFixes(rows: readonly StaleLinkPruneRow
 export declare function resolveGrantedFixScopes(rawScopes: readonly string[] | undefined): Set<ValidateFixScope>;
 /** Split a fix plan into the records that may be applied under the granted scopes and the gated records that were withheld. `--fix-scope` is an exact allowlist: every `--auto-fix` record requires its gate scope in `granted`. Ungated records (`--prune-missing` link prunes, governed by their own flag) are always applicable. */
 export declare function partitionFixesByGrant(fixes: readonly ValidateFixRecord[], granted: ReadonlySet<ValidateFixScope>): {
-    applicable: ValidateFixRecord[];
-    gated: ValidateFixRecord[];
+applicable: ValidateFixRecord[];
+gated: ValidateFixRecord[];
 };
 /** Compact serialization of a fix for planned/applied output rows. */
 export declare function toFixOutputRow(fix: ValidateFixRecord): Record<string, unknown>;

package/dist/core/validate/missing-by-type.d.ts

@@ -9,10 +9,10 @@
  */
 /** One missing required metadata field observed on an item of a specific type. */
 export interface MissingFieldOccurrence {
-    /** Item type name as stored in item metadata (e.g. "Task"). */
-    item_type: string;
-    /** Required metadata field that is missing on the item. */
-    field: string;
+/** Item type name as stored in item metadata (e.g. "Task"). */
+item_type: string;
+/** Required metadata field that is missing on the item. */
+field: string;
 }
 /** Aggregate missing-field occurrences into `{ type: { field: count } }` with both levels sorted lexicographically for stable, diff-friendly output. Zero counts never appear (only observed occurrences are aggregated). */
 export declare function buildMissingByTypeCounts(occurrences: Iterable<MissingFieldOccurrence>): Record<string, Record<string, number>>;

package/dist/core/validate/missing-link-owners.d.ts

@@ -16,45 +16,45 @@
 export type StaleLinkClassification = "moved" | "deleted" | "malformed";
 /** Documents the stale link owner input payload exchanged by command, SDK, and package integrations. */
 export interface StaleLinkOwnerInput {
-    /** Value that configures or reports item id for this contract. */
-    item_id: string;
-    /** Normalized workspace-relative path that no longer resolves. */
-    path: string;
-    /** Which link list of the owning item the path lives in. */
-    link_kind: "files" | "docs";
-    /** Value that configures or reports classification for this contract. */
-    classification: StaleLinkClassification;
+/** Value that configures or reports item id for this contract. */
+item_id: string;
+/** Normalized workspace-relative path that no longer resolves. */
+path: string;
+/** Which link list of the owning item the path lives in. */
+link_kind: "files" | "docs";
+/** Value that configures or reports classification for this contract. */
+classification: StaleLinkClassification;
 }
 /** Documents the missing linked path owner payload exchanged by command, SDK, and package integrations. */
 export interface MissingLinkedPathOwner {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Owning item type, `"Unknown"` if metadata is absent. */
-    type: string;
-    /** Owning item title, `""` if absent. */
-    title: string;
-    /** Owning item status, `""` if absent. */
-    status: string;
-    /** The link list the path lives in (= the input `link_kind`). */
-    field: "files" | "docs";
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Owning item type, `"Unknown"` if metadata is absent. */
+type: string;
+/** Owning item title, `""` if absent. */
+title: string;
+/** Owning item status, `""` if absent. */
+status: string;
+/** The link list the path lives in (= the input `link_kind`). */
+field: "files" | "docs";
 }
 /** Documents the missing linked path row payload exchanged by command, SDK, and package integrations. */
 export interface MissingLinkedPathRow {
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports classification for this contract. */
-    classification: StaleLinkClassification;
-    /** Value that configures or reports items for this contract. */
-    items: MissingLinkedPathOwner[];
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports classification for this contract. */
+classification: StaleLinkClassification;
+/** Value that configures or reports items for this contract. */
+items: MissingLinkedPathOwner[];
 }
 /** Documents the owner item metadata payload exchanged by command, SDK, and package integrations. */
 export interface OwnerItemMetadata {
-    /** Schema type that determines the shape and validation rules for this value. */
-    type?: string;
-    /** Value that configures or reports title for this contract. */
-    title?: string;
-    /** Lifecycle state reported for status. */
-    status?: string;
+/** Schema type that determines the shape and validation rules for this value. */
+type?: string;
+/** Value that configures or reports title for this contract. */
+title?: string;
+/** Lifecycle state reported for status. */
+status?: string;
 }
 /**
  * Group stale-link owner inputs by linked path and attach owning-item metadata.

package/dist/core/validate/stale-file-classification.d.ts

@@ -17,14 +17,14 @@
 export type StaleLinkedPathClassification = "moved" | "deleted" | "malformed";
 /** Documents the classified stale linked path payload exchanged by command, SDK, and package integrations. */
 export interface ClassifiedStaleLinkedPath {
-    /** Normalized workspace-relative stale linked path. */
-    path: string;
-    /** Value that configures or reports classification for this contract. */
-    classification: StaleLinkedPathClassification;
-    /** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted` and `malformed`. */
-    candidates: string[];
-    /** True when more candidates existed than `candidateLimit` allowed. */
-    candidates_truncated: boolean;
+/** Normalized workspace-relative stale linked path. */
+path: string;
+/** Value that configures or reports classification for this contract. */
+classification: StaleLinkedPathClassification;
+/** Candidate new locations (same basename, different path), sorted and capped at `candidateLimit`. Empty for `deleted` and `malformed`. */
+candidates: string[];
+/** True when more candidates existed than `candidateLimit` allowed. */
+candidates_truncated: boolean;
 }
 /** Fallback stale path candidate limit used when callers do not provide an override. */
 export declare const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;

package/dist/mcp/http-server.d.ts

@@ -10,24 +10,24 @@ import { type PmMcpHttpAuthorizationPolicy, type PmMcpProtectedResourceMetadata
 import { type JsonRpcRequest } from "./server.js";
 /** Runtime options for one real Streamable HTTP server. */
 export interface PmMcpHttpServerOptions {
-    /** Local bind host. Defaults to the DNS-rebinding-safe loopback address. */
-    host?: string;
-    /** TCP port. Zero requests an ephemeral port. */
-    port?: number;
-    /** Single modern MCP POST endpoint. */
-    endpointPath?: string;
-    /** Exact browser origins permitted when an Origin header is present. */
-    allowedOrigins?: readonly string[];
-    /** Optional RFC 9728/OAuth resource-server policy. */
-    authorization?: PmMcpHttpAuthorizationPolicy;
-    /** Metadata served at RFC 9728 well-known paths. */
-    protectedResourceMetadata?: PmMcpProtectedResourceMetadata;
-    /** Maximum accepted JSON request bytes. */
-    maximumBodyBytes?: number;
-    /** SSE comment interval; zero disables keep-alives. */
-    keepAliveMs?: number;
-    /** Optional embedding dispatcher; defaults to the canonical pm MCP handler. */
-    requestHandler?: (request: JsonRpcRequest) => unknown | Promise<unknown>;
+/** Local bind host. Defaults to the DNS-rebinding-safe loopback address. */
+host?: string;
+/** TCP port. Zero requests an ephemeral port. */
+port?: number;
+/** Single modern MCP POST endpoint. */
+endpointPath?: string;
+/** Exact browser origins permitted when an Origin header is present. */
+allowedOrigins?: readonly string[];
+/** Optional RFC 9728/OAuth resource-server policy. */
+authorization?: PmMcpHttpAuthorizationPolicy;
+/** Metadata served at RFC 9728 well-known paths. */
+protectedResourceMetadata?: PmMcpProtectedResourceMetadata;
+/** Maximum accepted JSON request bytes. */
+maximumBodyBytes?: number;
+/** SSE comment interval; zero disables keep-alives. */
+keepAliveMs?: number;
+/** Optional embedding dispatcher; defaults to the canonical pm MCP handler. */
+requestHandler?: (request: JsonRpcRequest) => unknown | Promise<unknown>;
 }
 /** Write one SSE event and wait for transport backpressure to clear. */
 export declare function writePmMcpSseEvent(response: ServerResponse, payload: unknown): Promise<void>;
@@ -41,20 +41,20 @@ export declare function closePmMcpHttpServer(server: Server): Promise<void>;
 export declare function startPmMcpHttpServer(options?: PmMcpHttpServerOptions): Promise<ReturnType<typeof createPmMcpHttpServer>>;
 /** Resolve loopback-safe bind defaults without opening a socket. */
 export declare function resolvePmMcpHttpListenAddress(options?: Pick<PmMcpHttpServerOptions, "host" | "port">): {
-    host: string;
-    port: number;
+host: string;
+port: number;
 };
 /** Resolve and harden executable HTTP options from an environment map. */
 export declare function resolvePmMcpHttpServerOptionsFromEnvironment(processEnvironment?: NodeJS.ProcessEnv): PmMcpHttpServerOptions;
 /** Internal HTTP transport seams used only by direct integration tests. */
 export declare const _testOnly: {
-    /** Return the first active request-scoped transport key for one server. */
-    activeSubscriptionKey: (server: Server) => symbol | undefined;
-    /** Open a stream against one server runtime without a network socket. */
-    openHttpSubscription: (server: Server, request: JsonRpcRequest, response: ServerResponse) => Promise<void>;
-    /** Exercise committed-response handling without a network race. */
-    writeMcpHttpDispatchError: typeof writeMcpHttpDispatchError;
-    /** Exercise the terminal request rejection handler without a live socket. */
-    destroyFailedMcpHttpResponse: typeof destroyFailedMcpHttpResponse;
+/** Return the first active request-scoped transport key for one server. */
+activeSubscriptionKey: (server: Server) => symbol | undefined;
+/** Open a stream against one server runtime without a network socket. */
+openHttpSubscription: (server: Server, request: JsonRpcRequest, response: ServerResponse) => Promise<void>;
+/** Exercise committed-response handling without a network race. */
+writeMcpHttpDispatchError: typeof writeMcpHttpDispatchError;
+/** Exercise the terminal request rejection handler without a live socket. */
+destroyFailedMcpHttpResponse: typeof destroyFailedMcpHttpResponse;
 };
 export {};

package/dist/mcp/legacy-adapter.d.ts

@@ -8,33 +8,33 @@ import { type AgentClientInfo } from "../sdk/runtime-primitives.js";
 import { PM_MCP_LEGACY_PROTOCOL_VERSIONS, type PmMcpImplementation, type PmMcpServerCapabilities } from "../sdk/mcp/protocol.js";
 /** Minimal request shape consumed by the compatibility adapter. */
 export interface LegacyMcpRequest {
-    /** Legacy method name. */
-    method?: string;
-    /** Legacy method parameters. */
-    params?: Record<string, unknown>;
+/** Legacy method name. */
+method?: string;
+/** Legacy method parameters. */
+params?: Record<string, unknown>;
 }
 /** Host callbacks keep this adapter separate from canonical SDK policy. */
 export interface LegacyMcpAdapterOptions {
-    /** Immutable server identity. */
-    serverInfo: PmMcpImplementation;
-    /** Compatibility-era capabilities. */
-    capabilities: PmMcpServerCapabilities;
-    /** Model-facing usage instructions. */
-    instructions: string;
-    /** Parse bounded historical client identity. */
-    parseClientInfo: (value: unknown) => AgentClientInfo | undefined;
-    /** Resolve legacy tool definitions. */
-    listTools: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
-    /** Execute one legacy tool call. */
-    callTool: (params: Record<string, unknown> | undefined, clientInfo: AgentClientInfo | undefined) => Promise<Record<string, unknown>>;
-    /** List legacy resources. */
-    listResources: () => Record<string, unknown>;
-    /** Read one legacy resource. */
-    readResource: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
-    /** List legacy prompts. */
-    listPrompts: () => Record<string, unknown>;
-    /** Render one legacy prompt. */
-    getPrompt: (params: Record<string, unknown> | undefined) => Record<string, unknown>;
+/** Immutable server identity. */
+serverInfo: PmMcpImplementation;
+/** Compatibility-era capabilities. */
+capabilities: PmMcpServerCapabilities;
+/** Model-facing usage instructions. */
+instructions: string;
+/** Parse bounded historical client identity. */
+parseClientInfo: (value: unknown) => AgentClientInfo | undefined;
+/** Resolve legacy tool definitions. */
+listTools: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+/** Execute one legacy tool call. */
+callTool: (params: Record<string, unknown> | undefined, clientInfo: AgentClientInfo | undefined) => Promise<Record<string, unknown>>;
+/** List legacy resources. */
+listResources: () => Record<string, unknown>;
+/** Read one legacy resource. */
+readResource: (params: Record<string, unknown> | undefined) => Promise<Record<string, unknown>>;
+/** List legacy prompts. */
+listPrompts: () => Record<string, unknown>;
+/** Render one legacy prompt. */
+getPrompt: (params: Record<string, unknown> | undefined) => Record<string, unknown>;
 }
 /**
  * Resolve the legacy revision a handshake negotiates, or refuse with the full
@@ -47,13 +47,13 @@ export interface LegacyMcpAdapterOptions {
 export declare function resolveLegacyProtocolVersion(requestedVersion: unknown): (typeof PM_MCP_LEGACY_PROTOCOL_VERSIONS)[number];
 /** Explicit compatibility adapter with no cross-process or modern-session role. */
 export declare class LegacyMcpAdapter {
-    #private;
-    /** Create one process-local legacy stdio adapter. */
-    constructor(options: LegacyMcpAdapterOptions);
-    /** Read the bounded identity most recently supplied to legacy initialize. */
-    getClientInfo(): AgentClientInfo | undefined;
-    /** Validate and answer the historical initialize handshake. */
-    initialize(params: Record<string, unknown> | undefined): Record<string, unknown>;
-    /** Dispatch one unversioned request through the finite legacy method set. */
-    dispatch(request: LegacyMcpRequest): Promise<Record<string, unknown>>;
+#private;
+/** Create one process-local legacy stdio adapter. */
+constructor(options: LegacyMcpAdapterOptions);
+/** Read the bounded identity most recently supplied to legacy initialize. */
+getClientInfo(): AgentClientInfo | undefined;
+/** Validate and answer the historical initialize handshake. */
+initialize(params: Record<string, unknown> | undefined): Record<string, unknown>;
+/** Dispatch one unversioned request through the finite legacy method set. */
+dispatch(request: LegacyMcpRequest): Promise<Record<string, unknown>>;
 }