@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/sdk/structured-mutations.js

@@ -1,2 +1,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]="ccd80f77-f619-5cd8-a792-cc5d9c733ebf")}catch{}})();import crypto from"node:crypto";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE,ITEM_PROJECT_CONTEXT_KEYS}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";import{runtimeFieldOptionTarget}from"../core/schema/runtime-schema.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";const MUTATION_ROW_KEYS=["op","id","reason","options"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),ITEM_FIELD_KEYS=new Set(["id","title","description","type","status","priority","tags","body","deadline","estimated_minutes","acceptance_criteria","definition_of_ready","order","rank","assignee",...ITEM_PROJECT_CONTEXT_KEYS,"affected_version","fixed_version","component","regression","customer_impact","close_reason","completed_at","dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index){if(options!==void 0){if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(options))if(!MUTATION_OPTION_KEYS[op].includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,MUTATION_OPTION_KEYS[op]);return options}}function validateMutationRow(value,index){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index);if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options}}function parseItemMutationBatch(input){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);return rows.map((row,index)=>{const mutation=validateMutationRow(row,index);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows){const graph=new Map;for(const row of rows){if(row.op!=="create"||typeof row.ref!="string")continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(row.ref,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseMutationDocumentRows(input){const parsed=parseJsonValue(input,"Mutation document"),envelope=Array.isArray(parsed)?{schema_version:1,mutations:parsed}:parsed;if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(row))if(!REFERENCED_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,REFERENCED_MUTATION_ROW_KEYS);return{...row}})}function collectMutationReferences(rows,options){const references=Object.create(null);for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input),references=collectMutationReferences(rows,options);assertAcyclicCreateReferences(rows);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows)),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);return{schema_version:1,mutations,references}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){const mappings=[["dependencies","dep",["id","kind","created_at","author","source_kind"]],["comments","comment",["text","created_at","author"]],["notes","note",["text","created_at","author"]],["learnings","learning",["text","created_at","author"]],["files","file",["path","scope","note"]],["tests","test",["command","scope","timeout_seconds"]],["docs","doc",["path","scope","note"]],["reminders","reminder",["at","text","created_at"]],["events","event",["start_at","end_at","title","location"]],["type_options","typeOption",["key","value"]]];for(const[sourceKey,targetKey,keys]of mappings){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions){if((mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key))return;const definition=runtimeFields.find(field=>field.metadata_key===key&&field.commands.includes(mode));if(definition!==void 0){const explicitValue=readRuntimeFieldOptionValue(explicitOptions,definition);documentOptions[runtimeFieldOptionTarget(definition)]=explicitValue!==void 0?explicitValue:definition.type==="array"||definition.type==="object"?JSON.stringify(value):value;return}if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(`${key}=${typeof value=="string"?value:JSON.stringify(value)}`),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}function itemDocumentToMutationOptions(input,mode,explicitOptions={},runtimeFields=[]){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item))appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions);if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),...Array.isArray(documentOptions.field)&&Array.isArray(explicitOptions.field)?{field:[...documentOptions.field,...explicitOptions.field]}:{},stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,validateItemMutationRows};
+(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]="7599b1e6-1f28-597a-adda-ad856beb35bd")}catch{}})();import crypto from"node:crypto";import{ITEM_MUTATION_FACET_OPTION_MAPPINGS}from"./lifecycle/mutation-facet-contracts.js";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE,ITEM_PROJECT_CONTEXT_KEYS}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";import{runtimeFieldOptionTarget}from"../core/schema/runtime-schema.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";const MUTATION_ROW_KEYS=["op","id","reason","options"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),ITEM_FIELD_KEYS=new Set(["id","title","description","type","status","priority","tags","body","deadline","estimated_minutes","acceptance_criteria","definition_of_ready","order","rank","assignee",...ITEM_PROJECT_CONTEXT_KEYS,"affected_version","fixed_version","component","regression","customer_impact","close_reason","completed_at","dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index){if(options!==void 0){if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(options))if(!MUTATION_OPTION_KEYS[op].includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,MUTATION_OPTION_KEYS[op]);return options}}function validateMutationRow(value,index){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index);if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options}}function parseItemMutationBatch(input){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);return rows.map((row,index)=>{const mutation=validateMutationRow(row,index);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows){const graph=new Map;for(const row of rows){if(row.op!=="create"||typeof row.ref!="string")continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(row.ref,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseMutationDocumentRows(input){const parsed=parseJsonValue(input,"Mutation document"),envelope=Array.isArray(parsed)?{schema_version:1,mutations:parsed}:parsed;if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(row))if(!REFERENCED_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,REFERENCED_MUTATION_ROW_KEYS);return{...row}})}function collectMutationReferences(rows,options){const references=Object.create(null);for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input),references=collectMutationReferences(rows,options);assertAcyclicCreateReferences(rows);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows)),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);return{schema_version:1,mutations,references}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){for(const[sourceKey,targetKey,keys]of ITEM_MUTATION_FACET_OPTION_MAPPINGS){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions){if((mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key))return;const definition=runtimeFields.find(field=>field.metadata_key===key&&field.commands.includes(mode));if(definition!==void 0){const explicitValue=readRuntimeFieldOptionValue(explicitOptions,definition);documentOptions[runtimeFieldOptionTarget(definition)]=explicitValue!==void 0?explicitValue:definition.type==="array"||definition.type==="object"?JSON.stringify(value):value;return}if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(`${key}=${typeof value=="string"?value:JSON.stringify(value)}`),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}function itemDocumentToMutationOptions(input,mode,explicitOptions={},runtimeFields=[]){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item))appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions);if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),...Array.isArray(documentOptions.field)&&Array.isArray(explicitOptions.field)?{field:[...documentOptions.field,...explicitOptions.field]}:{},stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,validateItemMutationRows};
 //# sourceMappingURL=structured-mutations.js.map

package/dist/sdk/telemetry.d.ts

@@ -6,70 +6,70 @@ export declare const TELEMETRY_SUBCOMMANDS: readonly ["status", "flush", "stats"
 export type TelemetrySubcommand = (typeof TELEMETRY_SUBCOMMANDS)[number];
 /** Local telemetry configuration, queue, and most recent flush state. */
 export interface TelemetryStatusSummary {
-    /** Whether telemetry delivery is enabled. */
-    enabled: boolean;
-    /** Persisted preference before process consent overrides. */
-    configured_enabled: boolean;
-    /** Process opt-outs, resolved without changing persisted preferences. */
-    env_overrides: ReturnType<typeof resolveTelemetryEnvironmentPolicy>;
-    /** Configured delivery endpoint. */
-    endpoint: string;
-    /** Local event queue path. */
-    queue_path: string;
-    /** Local telemetry state path. */
-    state_path: string;
-    /** Total queue rows, including invalid rows. */
-    queue_rows_total: number;
-    /** Valid queue entries eligible for delivery. */
-    queue_entries: number;
-    /** Invalid queue rows retained for diagnostics. */
-    queue_invalid_rows: number;
-    /** Queue file size in bytes. */
-    queue_size_bytes: number;
-    /** Most recent attempted flush time. */
-    last_attempted_flush_at: string | null;
-    /** Most recent successful flush time. */
-    last_successful_flush_at: string | null;
-    /** Most recent failed flush time. */
-    last_failed_flush_at: string | null;
-    /** Most recent failed flush message. */
-    last_failed_flush_error: string | null;
+/** Whether telemetry delivery is enabled. */
+enabled: boolean;
+/** Persisted preference before process consent overrides. */
+configured_enabled: boolean;
+/** Process opt-outs, resolved without changing persisted preferences. */
+env_overrides: ReturnType<typeof resolveTelemetryEnvironmentPolicy>;
+/** Configured delivery endpoint. */
+endpoint: string;
+/** Local event queue path. */
+queue_path: string;
+/** Local telemetry state path. */
+state_path: string;
+/** Total queue rows, including invalid rows. */
+queue_rows_total: number;
+/** Valid queue entries eligible for delivery. */
+queue_entries: number;
+/** Invalid queue rows retained for diagnostics. */
+queue_invalid_rows: number;
+/** Queue file size in bytes. */
+queue_size_bytes: number;
+/** Most recent attempted flush time. */
+last_attempted_flush_at: string | null;
+/** Most recent successful flush time. */
+last_successful_flush_at: string | null;
+/** Most recent failed flush time. */
+last_failed_flush_at: string | null;
+/** Most recent failed flush message. */
+last_failed_flush_error: string | null;
 }
 /** Precise receipt returned by a telemetry flush operation. */
 export interface TelemetryFlushResult {
-    /** Stable action discriminator. */
-    action: "telemetry";
-    /** Stable flush discriminator. */
-    subcommand: "flush";
-    /** Valid queue entries observed before the flush attempt. */
-    queue_entries_before: number;
-    /** Valid queue entries that remain after the flush attempt. */
-    queue_entries_after: number;
-    /** Number of valid queue entries removed by this flush attempt. */
-    queue_entries_drained: number;
-    /** Whether at least one valid queue entry was removed. */
-    queue_progressed: boolean;
-    /** Whether no valid queue entries remain. */
-    queue_empty: boolean;
-    /** Compatibility completion field; equivalent to `queue_empty`. */
-    queue_drained: boolean;
-    /** Complete post-flush telemetry status. */
-    status: TelemetryStatusSummary;
-    /** ISO timestamp at which the receipt was assembled. */
-    generated_at: string;
+/** Stable action discriminator. */
+action: "telemetry";
+/** Stable flush discriminator. */
+subcommand: "flush";
+/** Valid queue entries observed before the flush attempt. */
+queue_entries_before: number;
+/** Valid queue entries that remain after the flush attempt. */
+queue_entries_after: number;
+/** Number of valid queue entries removed by this flush attempt. */
+queue_entries_drained: number;
+/** Whether at least one valid queue entry was removed. */
+queue_progressed: boolean;
+/** Whether no valid queue entries remain. */
+queue_empty: boolean;
+/** Compatibility completion field; equivalent to `queue_empty`. */
+queue_drained: boolean;
+/** Complete post-flush telemetry status. */
+status: TelemetryStatusSummary;
+/** ISO timestamp at which the receipt was assembled. */
+generated_at: string;
 }
 /** Documents the telemetry command options payload exchanged by command, SDK, and package integrations. */
 export interface TelemetryCommandOptions {
-    /** Value that configures or reports subcommand for this contract. */
-    subcommand?: string;
-    /** Value that configures or reports limit for this contract. */
-    limit?: string | number;
+/** Value that configures or reports subcommand for this contract. */
+subcommand?: string;
+/** Value that configures or reports limit for this contract. */
+limit?: string | number;
 }
 /** Count one resolved deprecated command alias in consented, local-only telemetry state. */
 export declare function recordDeprecatedAliasUsage(alias: string): Promise<boolean>;
 /** Run telemetry flush with a precise completion receipt. */
 export declare function runTelemetry(options: TelemetryCommandOptions & {
-    subcommand: "flush";
+subcommand: "flush";
 }, global: GlobalOptions): Promise<TelemetryFlushResult>;
 /** Run any telemetry subcommand through the public runtime surface. */
 export declare function runTelemetry(options: TelemetryCommandOptions, global: GlobalOptions): Promise<Record<string, unknown>>;

package/dist/sdk/templates.d.ts

@@ -5,57 +5,57 @@ export type CreateTemplateOptions = Record<string, TemplateOptionValue>;
 /** Restricts template source values accepted by command, SDK, and storage contracts. */
 export type TemplateSource = "builtin" | "user";
 interface StoredCreateTemplateDocument {
-    name: string;
-    created_at: string;
-    updated_at: string;
-    options: CreateTemplateOptions;
+name: string;
+created_at: string;
+updated_at: string;
+options: CreateTemplateOptions;
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    normalizeTemplateName: typeof normalizeTemplateName;
-    extractTemplateOptions: typeof extractTemplateOptions;
-    parseStoredTemplateDocument: typeof parseStoredTemplateDocument;
-    builtinTemplateDocument: typeof builtinTemplateDocument;
-    readStoredTemplateDocument: typeof readStoredTemplateDocument;
+normalizeTemplateName: typeof normalizeTemplateName;
+extractTemplateOptions: typeof extractTemplateOptions;
+parseStoredTemplateDocument: typeof parseStoredTemplateDocument;
+builtinTemplateDocument: typeof builtinTemplateDocument;
+readStoredTemplateDocument: typeof readStoredTemplateDocument;
 };
 /** Documents the templates save result payload exchanged by command, SDK, and package integrations. */
 export interface TemplatesSaveResult {
-    /** Value that configures or reports name for this contract. */
-    name: string;
-    /** ISO 8601 timestamp recording when created occurred. */
-    created_at: string;
-    /** ISO 8601 timestamp recording when updated occurred. */
-    updated_at: string;
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports options for this contract. */
-    options: CreateTemplateOptions;
+/** Value that configures or reports name for this contract. */
+name: string;
+/** ISO 8601 timestamp recording when created occurred. */
+created_at: string;
+/** ISO 8601 timestamp recording when updated occurred. */
+updated_at: string;
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports options for this contract. */
+options: CreateTemplateOptions;
 }
 /** Documents the templates list result payload exchanged by command, SDK, and package integrations. */
 export interface TemplatesListResult {
-    /** Value that configures or reports templates for this contract. */
-    templates: string[];
-    /** Value that configures or reports count for this contract. */
-    count: number;
-    /** Value that configures or reports builtin templates for this contract. */
-    builtin_templates: string[];
-    /** Value that configures or reports user templates for this contract. */
-    user_templates: string[];
+/** Value that configures or reports templates for this contract. */
+templates: string[];
+/** Value that configures or reports count for this contract. */
+count: number;
+/** Value that configures or reports builtin templates for this contract. */
+builtin_templates: string[];
+/** Value that configures or reports user templates for this contract. */
+user_templates: string[];
 }
 /** Documents the templates show result payload exchanged by command, SDK, and package integrations. */
 export interface TemplatesShowResult {
-    /** Value that configures or reports name for this contract. */
-    name: string;
-    /** Value that configures or reports source for this contract. */
-    source: TemplateSource;
-    /** ISO 8601 timestamp recording when created occurred. */
-    created_at: string;
-    /** ISO 8601 timestamp recording when updated occurred. */
-    updated_at: string;
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports options for this contract. */
-    options: CreateTemplateOptions;
+/** Value that configures or reports name for this contract. */
+name: string;
+/** Value that configures or reports source for this contract. */
+source: TemplateSource;
+/** ISO 8601 timestamp recording when created occurred. */
+created_at: string;
+/** ISO 8601 timestamp recording when updated occurred. */
+updated_at: string;
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports options for this contract. */
+options: CreateTemplateOptions;
 }
 declare function normalizeTemplateName(rawName: string): string;
 declare function extractTemplateOptions(rawOptions: Record<string, unknown>): CreateTemplateOptions;

package/dist/sdk/test/batch.d.ts

@@ -3,100 +3,100 @@ import type { ItemStatus, LinkedTest } from "../../types/index.js";
 import { type LinkedTestFailureCategory, type TestRunResult } from "./execution.js";
 /** Documents the test all command options payload exchanged by command, SDK, and package integrations. */
 export interface TestAllCommandOptions {
-    /** Explicit author recorded on item test-run tracking events. */
-    author?: string;
-    /** Lifecycle state reported for status. */
-    status?: string;
-    /** Value that configures or reports limit for this contract. */
-    limit?: string;
-    /** Value that configures or reports offset for this contract. */
-    offset?: string;
-    /** Value that configures or reports timeout for this contract. */
-    timeout?: string;
-    /** Value that configures or reports progress for this contract. */
-    progress?: boolean;
-    /** Value that configures or reports env set for this contract. */
-    envSet?: string[];
-    /** Value that configures or reports env clear for this contract. */
-    envClear?: string[];
-    /** Value that configures or reports shared host safe for this contract. */
-    sharedHostSafe?: boolean;
-    /** Value that configures or reports pm context for this contract. */
-    pmContext?: string;
-    /** Value that configures or reports override linked pm context for this contract. */
-    overrideLinkedPmContext?: boolean;
-    /** Source-workspace visibility and working-directory mode. */
-    workspaceContext?: string;
-    /** Force run-level source-workspace mode over linked metadata. */
-    overrideLinkedWorkspaceContext?: boolean;
-    /** Explicitly permit untrusted commands when project policy also permits them. */
-    allowUntrustedLinkedTests?: boolean;
-    /** Value that configures or reports fail on context mismatch for this contract. */
-    failOnContextMismatch?: boolean;
-    /** Value that configures or reports fail on skipped for this contract. */
-    failOnSkipped?: boolean;
-    /** Value that configures or reports fail on empty test run for this contract. */
-    failOnEmptyTestRun?: boolean;
-    /** Value that configures or reports require assertions for pm for this contract. */
-    requireAssertionsForPm?: boolean;
-    /** Value that configures or reports check context for this contract. */
-    checkContext?: boolean;
-    /** Value that configures or reports auto pm context for this contract. */
-    autoPmContext?: boolean;
+/** Explicit author recorded on item test-run tracking events. */
+author?: string;
+/** Lifecycle state reported for status. */
+status?: string;
+/** Value that configures or reports limit for this contract. */
+limit?: string;
+/** Value that configures or reports offset for this contract. */
+offset?: string;
+/** Value that configures or reports timeout for this contract. */
+timeout?: string;
+/** Value that configures or reports progress for this contract. */
+progress?: boolean;
+/** Value that configures or reports env set for this contract. */
+envSet?: string[];
+/** Value that configures or reports env clear for this contract. */
+envClear?: string[];
+/** Value that configures or reports shared host safe for this contract. */
+sharedHostSafe?: boolean;
+/** Value that configures or reports pm context for this contract. */
+pmContext?: string;
+/** Value that configures or reports override linked pm context for this contract. */
+overrideLinkedPmContext?: boolean;
+/** Source-workspace visibility and working-directory mode. */
+workspaceContext?: string;
+/** Force run-level source-workspace mode over linked metadata. */
+overrideLinkedWorkspaceContext?: boolean;
+/** Explicitly permit untrusted commands when project policy also permits them. */
+allowUntrustedLinkedTests?: boolean;
+/** Value that configures or reports fail on context mismatch for this contract. */
+failOnContextMismatch?: boolean;
+/** Value that configures or reports fail on skipped for this contract. */
+failOnSkipped?: boolean;
+/** Value that configures or reports fail on empty test run for this contract. */
+failOnEmptyTestRun?: boolean;
+/** Value that configures or reports require assertions for pm for this contract. */
+requireAssertionsForPm?: boolean;
+/** Value that configures or reports check context for this contract. */
+checkContext?: boolean;
+/** Value that configures or reports auto pm context for this contract. */
+autoPmContext?: boolean;
 }
 /** Documents the test all item result payload exchanged by command, SDK, and package integrations. */
 export interface TestAllItemResult {
-    /** Whether the operation completed without a blocking failure. */
-    ok: boolean;
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Lifecycle state reported for status. */
-    status: ItemStatus;
-    /** Number of test entries represented by this result. */
-    test_count: number;
-    /** Value that configures or reports passed for this contract. */
-    passed: number;
-    /** Value that configures or reports failed for this contract. */
-    failed: number;
-    /** Value that configures or reports skipped for this contract. */
-    skipped: number;
-    /** Executes the results operation through the package runtime. */
-    run_results: TestRunResult[];
-    /** Value that configures or reports failure categories for this contract. */
-    failure_categories: Record<LinkedTestFailureCategory, number>;
+/** Whether the operation completed without a blocking failure. */
+ok: boolean;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Lifecycle state reported for status. */
+status: ItemStatus;
+/** Number of test entries represented by this result. */
+test_count: number;
+/** Value that configures or reports passed for this contract. */
+passed: number;
+/** Value that configures or reports failed for this contract. */
+failed: number;
+/** Value that configures or reports skipped for this contract. */
+skipped: number;
+/** Executes the results operation through the package runtime. */
+run_results: TestRunResult[];
+/** Value that configures or reports failure categories for this contract. */
+failure_categories: Record<LinkedTestFailureCategory, number>;
 }
 /** Documents the test all result payload exchanged by command, SDK, and package integrations. */
 export interface TestAllResult {
-    /** Whether the operation completed without a blocking failure. */
-    ok: boolean;
-    /** Value that configures or reports totals for this contract. */
-    totals: {
-        items: number;
-        linked_tests: number;
-        passed: number;
-        failed: number;
-        skipped: number;
-        failure_categories: Record<LinkedTestFailureCategory, number>;
-    };
-    /** Value that configures or reports failed for this contract. */
-    failed: number;
-    /** Value that configures or reports passed for this contract. */
-    passed: number;
-    /** Value that configures or reports skipped for this contract. */
-    skipped: number;
-    /** Value that configures or reports fail on skipped triggered for this contract. */
-    fail_on_skipped_triggered?: boolean;
-    /** Value that configures or reports fail on empty test run triggered for this contract. */
-    fail_on_empty_test_run_triggered?: boolean;
-    /** Value that configures or reports warnings for this contract. */
-    warnings?: string[];
-    /** Value that configures or reports results for this contract. */
-    results: TestAllItemResult[];
+/** Whether the operation completed without a blocking failure. */
+ok: boolean;
+/** Value that configures or reports totals for this contract. */
+totals: {
+items: number;
+linked_tests: number;
+passed: number;
+failed: number;
+skipped: number;
+failure_categories: Record<LinkedTestFailureCategory, number>;
+};
+/** Value that configures or reports failed for this contract. */
+failed: number;
+/** Value that configures or reports passed for this contract. */
+passed: number;
+/** Value that configures or reports skipped for this contract. */
+skipped: number;
+/** Value that configures or reports fail on skipped triggered for this contract. */
+fail_on_skipped_triggered?: boolean;
+/** Value that configures or reports fail on empty test run triggered for this contract. */
+fail_on_empty_test_run_triggered?: boolean;
+/** Value that configures or reports warnings for this contract. */
+warnings?: string[];
+/** Value that configures or reports results for this contract. */
+results: TestAllItemResult[];
 }
 /** Implements run test all for the public runtime surface of this module. */
 export declare const runTestAll: (options: TestAllCommandOptions, global: GlobalOptions) => Promise<TestAllResult>;
 /** Public contract for test only test all, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyTestAll: {
-    buildLinkedTestKey: (test: LinkedTest) => string;
-    formatTrackingError: (error: unknown) => string;
+buildLinkedTestKey: (test: LinkedTest) => string;
+formatTrackingError: (error: unknown) => string;
 };

package/dist/sdk/test/batch.js

@@ -1,3 +1,3 @@
-(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]="8371273e-fb3c-5615-bd0e-f7aeb2a0b303")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{parseOptionalNumber}from"../../core/item/parse.js";import{normalizeStatusInput}from"../../core/item/status.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{nowIso}from"../../core/shared/time.js";import{listAllItemMetadataLight}from"../../core/store/item-store.js";import{resolveGlobalPmRoot,resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{appendTrackedTestRunSummary}from"../../core/test/item-test-run-tracking.js";import{resolveAuthor}from"../../core/shared/author.js";import{countFailureCategories,runLinkedTests,runTest,summarizeContextPreflight}from"./execution.js";const parseStatus=(raw,statusRegistry)=>{if(raw===void 0)return;const normalized=normalizeStatusInput(raw,statusRegistry);if(!normalized){const allowedStatuses=statusRegistry.definitions.map(definition=>definition.id);throw new PmCliError(`Invalid --status value "${raw}". Allowed: ${allowedStatuses.join(", ")}`,EXIT_CODE.USAGE)}return normalized},parseTimeout=raw=>{if(raw===void 0)return;const parsed=parseOptionalNumber(raw,"timeout");if(parsed<=0)throw new PmCliError("timeout must be a positive number",EXIT_CODE.USAGE);return parsed},parseNonNegativeInteger=(raw,flag)=>{if(raw===void 0)return;const parsed=Number(raw);if(!Number.isInteger(parsed)||parsed<0)throw new PmCliError(`${flag} must be a non-negative integer`,EXIT_CODE.USAGE);return parsed},formatTrackingError=error=>error instanceof Error?error.message:String(error),resolveTrackedRunId=()=>{const fromEnv=process.env.PM_BACKGROUND_TEST_RUN_ID?.trim();return fromEnv&&fromEnv.length>0?fromEnv:`test-all-local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,8)}`},normalizeCommand=command=>command.trim().replaceAll(/\s+/g," "),normalizeEnvSetSignature=value=>!value||Object.keys(value).length===0?"{}":JSON.stringify(Object.fromEntries(Object.entries(value).sort(([left],[right])=>left.localeCompare(right)))),normalizeEnvClearSignature=value=>!value||value.length===0?"[]":JSON.stringify([...value].sort((left,right)=>left.localeCompare(right))),normalizePmContextModeSignature=value=>{const normalized=value?.trim().toLowerCase();return normalized&&normalized.length>0?normalized:"none"},normalizeWorkspaceContextModeSignature=value=>{const normalized=value?.trim().toLowerCase();return normalized&&normalized.length>0?normalized:"source"},normalizeAssertionStrings=values=>[...new Set(values??[])].sort((left,right)=>left.localeCompare(right)),normalizeAssertionMap=value=>Object.fromEntries(Object.entries(value??{}).sort(([left],[right])=>left.localeCompare(right))),normalizeAssertionLineCount=value=>typeof value=="number"?value:void 0,normalizeAssertionSignature=test=>{const normalized={assert_stdout_contains:normalizeAssertionStrings(test.assert_stdout_contains),assert_stdout_regex:normalizeAssertionStrings(test.assert_stdout_regex),assert_stderr_contains:normalizeAssertionStrings(test.assert_stderr_contains),assert_stderr_regex:normalizeAssertionStrings(test.assert_stderr_regex),assert_stdout_min_lines:normalizeAssertionLineCount(test.assert_stdout_min_lines),assert_json_field_equals:normalizeAssertionMap(test.assert_json_field_equals),assert_json_field_gte:normalizeAssertionMap(test.assert_json_field_gte)};return JSON.stringify(normalized)},resolveLinkedTestTargetSignature=test=>{const command=resolveOptionalEnvironmentValue(test.command);return command!==void 0?`command:${test.scope}:${normalizeCommand(command)}`:`path:${test.scope}:${resolveOptionalEnvironmentValue(test.path)??""}`},buildLinkedTestKey=test=>{const envSet=normalizeEnvSetSignature(test.env_set),envClear=normalizeEnvClearSignature(test.env_clear),pmContextMode=normalizePmContextModeSignature(test.pm_context_mode),workspaceContextMode=normalizeWorkspaceContextModeSignature(test.workspace_context_mode),sharedHostSafe=test.shared_host_safe===!0?"true":"false",assertions=normalizeAssertionSignature(test);return`${resolveLinkedTestTargetSignature(test)}:${envSet}:${envClear}:${pmContextMode}:${workspaceContextMode}:${sharedHostSafe}:${assertions}`},maxTimeoutSeconds=(current,candidate)=>candidate===void 0?current:current===void 0||candidate>current?candidate:current,countStatuses=runResults=>{let passed=0,failed=0,skipped=0;for(const result of runResults){if(result.status==="passed"){passed+=1;continue}if(result.status==="failed"){failed+=1;continue}skipped+=1}return{passed,failed,skipped}},mergeFailureCategoryCounts=(target,source)=>{for(const[key,value]of Object.entries(source))target[key]+=value},emitTestAllProgress=(options,message)=>{if(options.progress===!0)try{process.stderr.write(`[pm test-all] ${message}
+(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]="61f797d4-1c7c-52f2-83a9-818c2faca5ff")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{parseOptionalNumber}from"../../core/item/parse.js";import{normalizeStatusInput}from"../../core/item/status.js";import{resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{nowIso}from"../../core/shared/time.js";import{listAllItemMetadataLight}from"../../core/store/item-store.js";import{resolveGlobalPmRoot,resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{appendTrackedTestRunSummary}from"../../core/test/item-test-run-tracking.js";import{resolveAuthor}from"../../core/shared/author.js";import{countFailureCategories,runLinkedTests,runTest,summarizeContextPreflight}from"./execution.js";const parseStatus=(raw,statusRegistry)=>{if(raw===void 0)return;const normalized=normalizeStatusInput(raw,statusRegistry);if(!normalized){const allowedStatuses=statusRegistry.definitions.map(definition=>definition.id);throw new PmCliError(`Invalid --status value "${raw}". Allowed: ${allowedStatuses.join(", ")}`,EXIT_CODE.USAGE)}return normalized},parseTimeout=raw=>{if(raw===void 0)return;const parsed=parseOptionalNumber(raw,"timeout");if(parsed<=0)throw new PmCliError("timeout must be a positive number",EXIT_CODE.USAGE);return parsed},parseNonNegativeInteger=(raw,flag)=>{if(raw===void 0)return;const parsed=Number(raw);if(!Number.isInteger(parsed)||parsed<0)throw new PmCliError(`${flag} must be a non-negative integer`,EXIT_CODE.USAGE);return parsed},formatTrackingError=error=>error instanceof Error?error.message:String(error),resolveTrackedRunId=()=>{const fromEnv=process.env.PM_BACKGROUND_TEST_RUN_ID?.trim();return fromEnv&&fromEnv.length>0?fromEnv:`test-all-local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2,8)}`},normalizeCommand=command=>command.trim().replaceAll(/\s+/g," "),normalizeEnvSetSignature=value=>!value||Object.keys(value).length===0?"{}":JSON.stringify(Object.fromEntries(Object.entries(value).sort(([left],[right])=>left.localeCompare(right)))),normalizeEnvClearSignature=value=>!value||value.length===0?"[]":JSON.stringify([...value].sort((left,right)=>left.localeCompare(right))),normalizePmContextModeSignature=value=>{const normalized=value?.trim().toLowerCase();return normalized&&normalized.length>0?normalized:"none"},normalizeWorkspaceContextModeSignature=value=>{const normalized=value?.trim().toLowerCase();return normalized&&normalized.length>0?normalized:"source"},normalizeAssertionStrings=values=>[...new Set(values??[])].sort((left,right)=>left.localeCompare(right)),normalizeAssertionMap=value=>Object.fromEntries(Object.entries(value??{}).sort(([left],[right])=>left.localeCompare(right))),normalizeAssertionLineCount=value=>typeof value=="number"?value:void 0,normalizeAssertionSignature=test=>{const normalized={assert_stdout_contains:normalizeAssertionStrings(test.assert_stdout_contains),assert_stdout_regex:normalizeAssertionStrings(test.assert_stdout_regex),assert_stderr_contains:normalizeAssertionStrings(test.assert_stderr_contains),assert_stderr_regex:normalizeAssertionStrings(test.assert_stderr_regex),assert_stdout_min_lines:normalizeAssertionLineCount(test.assert_stdout_min_lines),assert_json_field_equals:normalizeAssertionMap(test.assert_json_field_equals),assert_json_field_gte:normalizeAssertionMap(test.assert_json_field_gte)};return JSON.stringify(normalized)},resolveLinkedTestTargetSignature=test=>{const command=resolveOptionalEnvironmentValue(test.command);return command!==void 0?`command:${test.scope}:${normalizeCommand(command)}`:`path:${test.scope}:${resolveOptionalEnvironmentValue(test.path)??""}`},buildLinkedTestKey=test=>{const envSet=normalizeEnvSetSignature(test.env_set),envClear=normalizeEnvClearSignature(test.env_clear),pmContextMode=normalizePmContextModeSignature(test.pm_context_mode),workspaceContextMode=normalizeWorkspaceContextModeSignature(test.workspace_context_mode),sharedHostSafe=test.shared_host_safe===!0?"true":"false",assertions=normalizeAssertionSignature(test);return`${resolveLinkedTestTargetSignature(test)}:${envSet}:${envClear}:${pmContextMode}:${workspaceContextMode}:${sharedHostSafe}:${assertions}`},maxTimeoutSeconds=(current,candidate)=>candidate===void 0?current:current===void 0||candidate>current?candidate:current,countStatuses=runResults=>{let passed=0,failed=0,skipped=0;for(const result of runResults){if(result.status==="passed"){passed+=1;continue}if(result.status==="failed"||result.status==="refused"){failed+=1;continue}skipped+=1}return{passed,failed,skipped}},mergeFailureCategoryCounts=(target,source)=>{for(const[key,value]of Object.entries(source))target[key]+=value},emitTestAllProgress=(options,message)=>{if(options.progress===!0)try{process.stderr.write(`[pm test-all] ${message}
 `)}catch{}},collectTestAllItemTests=async(filteredItems,global2,pmRoot)=>{const itemTests=[];let linkedTests=0;for(const item of filteredItems){const readResult=await runTest(item.id,{run:!1},{...global2,path:pmRoot});linkedTests+=readResult.tests.length,itemTests.push({item,tests:readResult.tests})}return{itemTests,linkedTests}},selectTestAllItems=async params=>{const statusRegistry=resolveRuntimeStatusRegistry(params.settings.schema),typeRegistry=resolveItemTypeRegistry(params.settings,getActiveExtensionRegistrations()),statusFilter=parseStatus(params.options.status,statusRegistry),limitFilter=parseNonNegativeInteger(params.options.limit,"--limit"),offsetFilter=parseNonNegativeInteger(params.options.offset,"--offset")??0,statusFilteredItems=(await listAllItemMetadataLight(params.pmRoot,params.settings.item_format,typeRegistry.type_to_folder,void 0,params.settings.schema)).filter(item=>statusFilter?item.status===statusFilter:!0).sort((a,b)=>a.id.localeCompare(b.id));return{filteredItems:limitFilter===void 0?statusFilteredItems.slice(offsetFilter):statusFilteredItems.slice(offsetFilter,offsetFilter+limitFilter),statusFilter,limitFilter,offsetFilter}},buildEffectiveTimeoutByKey=itemTests=>{const effectiveTimeoutByKey=new Map;for(const{tests}of itemTests)for(const test of tests){const key=buildLinkedTestKey(test);if(!effectiveTimeoutByKey.has(key)){effectiveTimeoutByKey.set(key,test.timeout_seconds);continue}effectiveTimeoutByKey.set(key,maxTimeoutSeconds(effectiveTimeoutByKey.get(key),test.timeout_seconds))}return effectiveTimeoutByKey},runTestAllItem=async(entry,context)=>{const testsToRun=[],keyedTests=entry.tests.map(test=>{const key=buildLinkedTestKey(test),duplicate=context.seenTestKeys.has(key);if(!duplicate){context.seenTestKeys.add(key);const effectiveTimeoutSeconds=context.effectiveTimeoutByKey.get(key);testsToRun.push(effectiveTimeoutSeconds===void 0?test:{...test,timeout_seconds:effectiveTimeoutSeconds})}return{test,key,duplicate}}),executedResults=testsToRun.length>0?await runLinkedTests(testsToRun,context.defaultTimeoutSeconds,{progress:context.options.progress,sourceRoots:context.sourceRoots,envSet:context.options.envSet,envClear:context.options.envClear,sharedHostSafe:context.options.sharedHostSafe,pmContext:context.options.pmContext,overrideLinkedPmContext:context.options.overrideLinkedPmContext,failOnContextMismatch:context.options.failOnContextMismatch,failOnEmptyTestRun:context.options.failOnEmptyTestRun,requireAssertionsForPm:context.options.requireAssertionsForPm,checkContext:context.options.checkContext,autoPmContext:context.options.autoPmContext,workspaceContext:context.options.workspaceContext,overrideLinkedWorkspaceContext:context.options.overrideLinkedWorkspaceContext,pmRoot:context.pmRoot,allowUntrustedLinkedTests:context.options.allowUntrustedLinkedTests,untrustedLinkedTestsPolicyEnabled:context.settings.testing.allow_untrusted_linked_tests}):[];let executedIndex=0;const runResults=keyedTests.map(({test,key,duplicate})=>{if(!duplicate){const executed=executedResults[executedIndex];return executedIndex+=1,executed}return{command:test.command,path:test.path,status:"skipped",error:`Duplicate linked test skipped (key=${key}).`}}),summary=countStatuses(runResults),failureCategories=countFailureCategories(runResults),trackingWarnings=await appendTestAllItemTracking(entry,summary,runResults,context);return{passed:summary.passed,failed:summary.failed,skipped:summary.skipped,trackingWarnings,failureCategories,result:{ok:summary.failed===0&&!(context.options.failOnSkipped===!0&&summary.skipped>0),id:entry.item.id,status:entry.item.status,test_count:entry.tests.length,passed:summary.passed,failed:summary.failed,skipped:summary.skipped,run_results:runResults,failure_categories:failureCategories}}},trackedRunFailed=(summary,options)=>[summary.failed>0,options.failOnSkipped===!0&&summary.skipped>0].includes(!0),optionalTrue=value=>value?!0:void 0,appendTestAllItemTracking=async(entry,summary,runResults,context)=>{if(!context.trackingEnabled)return[];try{const failed=trackedRunFailed(summary,context.options);await appendTrackedTestRunSummary({pmRoot:context.pmRoot,settings:context.settings,itemId:entry.item.id,author:context.trackingAuthor,message:`Track test-all run summary (${context.trackingRunId})`,entry:{run_id:context.trackingRunId,kind:"test-all",status:failed?"failed":"passed",started_at:context.runStartedAt,finished_at:nowIso(),recorded_at:nowIso(),attempt:context.trackingAttempt,resumed_from:context.trackingResumedFrom,passed:summary.passed,failed:summary.failed,skipped:summary.skipped,items:1,linked_tests:entry.tests.length,fail_on_skipped_triggered:optionalTrue(context.options.failOnSkipped===!0&&summary.skipped>0),executions:runResults.filter(result=>result.command?.trim()).slice(0,32).map(result=>({command:result.command.trim(),requested_pm_context_mode:result.execution_context?.requested_pm_context_mode,pm_context_mode:result.execution_context?.pm_context_mode,workspace_context_mode:result.execution_context?.workspace_context_mode,trust_reason:result.execution_context?.trust.reason}))}})}catch(error){return[`test_result_tracking_failed:${entry.item.id}:${formatTrackingError(error)}`]}return[]},resolveTrackingAttempt=()=>{const raw=process.env.PM_BACKGROUND_TEST_RUN_ATTEMPT?.trim(),parsed=raw?Number.parseInt(raw,10):Number.NaN;return Number.isFinite(parsed)&&parsed>=1?parsed:void 0},resolveOptionalEnvironmentValue=value=>{const trimmed=value?.trim();return trimmed&&trimmed.length>0?trimmed:void 0},buildTestAllItemRunContext=params=>({pmRoot:params.pmRoot,settings:params.settings,options:params.options,defaultTimeoutSeconds:params.defaultTimeoutSeconds,sourceRoots:{projectPmRoot:params.pmRoot,globalPmRoot:resolveGlobalPmRoot(process.cwd())},seenTestKeys:new Set,effectiveTimeoutByKey:buildEffectiveTimeoutByKey(params.itemTests),trackingEnabled:params.settings.testing.record_results_to_items===!0,trackingAuthor:resolveAuthor(params.options.author,params.settings.author_default),trackingRunId:resolveTrackedRunId(),trackingAttempt:resolveTrackingAttempt(),trackingResumedFrom:resolveOptionalEnvironmentValue(process.env.PM_BACKGROUND_TEST_RUN_RESUMED_FROM),runStartedAt:params.runStartedAt}),initializeTestAllAccumulation=(options,linkedTests,filteredItems)=>{const accumulation={results:[],passed:0,failed:0,skipped:0,failureCategories:countFailureCategories([]),trackingWarnings:[]},failOnEmptyTestRunTriggered=options.failOnEmptyTestRun===!0&&linkedTests===0;return failOnEmptyTestRunTriggered&&(accumulation.failed+=1,accumulation.failureCategories.empty_run+=1,accumulation.trackingWarnings.push(`empty_linked_test_selection:items=${filteredItems.length};linked_tests=0;fail_on_empty_test_run=true`)),{accumulation,failOnEmptyTestRunTriggered}},runTestAllItems=async(itemTests,context,accumulation)=>{for(const[itemIndex,entry]of itemTests.entries()){emitTestAllProgress(context.options,`item ${itemIndex+1}/${itemTests.length} start id=${entry.item.id} linked_tests=${entry.tests.length}`);const execution=await runTestAllItem(entry,context);mergeFailureCategoryCounts(accumulation.failureCategories,execution.failureCategories),accumulation.passed+=execution.passed,accumulation.failed+=execution.failed,accumulation.skipped+=execution.skipped,accumulation.trackingWarnings.push(...execution.trackingWarnings),accumulation.results.push(execution.result),emitTestAllProgress(context.options,`item ${itemIndex+1}/${itemTests.length} end id=${entry.item.id} status=${execution.failed===0?"passed":"failed"} passed=${execution.passed} failed=${execution.failed} skipped=${execution.skipped}`)}},appendContextPreflightWarning=(options,accumulation)=>{if(options.checkContext!==!0)return;const allRunResults=accumulation.results.flatMap(entry=>entry.run_results),preflight=summarizeContextPreflight(allRunResults);accumulation.trackingWarnings.push(`context_preflight:checked_pm_commands=${preflight.checked_pm_commands};tracker_read_commands=${preflight.tracker_read_commands};mismatches=${preflight.mismatches};auto_remediated=${preflight.auto_remediated}`)},buildTestAllResult=params=>({ok:params.ok,totals:{items:params.filteredItems.length,linked_tests:params.linkedTests,passed:params.accumulation.passed,failed:params.accumulation.failed,skipped:params.accumulation.skipped,failure_categories:params.accumulation.failureCategories},failed:params.accumulation.failed,passed:params.accumulation.passed,skipped:params.accumulation.skipped,fail_on_skipped_triggered:params.failOnSkippedTriggered?!0:void 0,fail_on_empty_test_run_triggered:params.failOnEmptyTestRunTriggered?!0:void 0,warnings:params.accumulation.trackingWarnings.length>0?params.accumulation.trackingWarnings:void 0,results:params.accumulation.results}),buildTestAllSelectionProgress=params=>[`selection items=${params.filteredItems.length}`,`linked_tests=${params.linkedTests}`,params.statusFilter===void 0?"":`status=${params.statusFilter}`,params.limitFilter===void 0?"":`limit=${params.limitFilter}`,params.offsetFilter>0?`offset=${params.offsetFilter}`:""].filter(entry=>entry.length>0).join(" "),prepareTestAllRun=async(options,global2)=>{const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),selection=await selectTestAllItems({pmRoot,settings,options}),defaultTimeoutSeconds=parseTimeout(options.timeout),runStartedAt=nowIso(),collected=await collectTestAllItemTests(selection.filteredItems,global2,pmRoot);return emitTestAllProgress(options,buildTestAllSelectionProgress({...selection,linkedTests:collected.linkedTests})),{pmRoot,settings,filteredItems:selection.filteredItems,itemTests:collected.itemTests,linkedTests:collected.linkedTests,defaultTimeoutSeconds,runStartedAt}},resolveTestAllOutcome=params=>{const failOnSkippedTriggered=params.options.failOnSkipped===!0&&params.accumulation.skipped>0,ok=![params.accumulation.failed>0,failOnSkippedTriggered,params.failOnEmptyTestRunTriggered].includes(!0);return{failOnSkippedTriggered,ok}},runTestAll=async(options,global2)=>{const prepared=await prepareTestAllRun(options,global2),{accumulation,failOnEmptyTestRunTriggered}=initializeTestAllAccumulation(options,prepared.linkedTests,prepared.filteredItems),itemRunContext=buildTestAllItemRunContext({pmRoot:prepared.pmRoot,settings:prepared.settings,options,itemTests:prepared.itemTests,defaultTimeoutSeconds:prepared.defaultTimeoutSeconds,runStartedAt:prepared.runStartedAt});await runTestAllItems(prepared.itemTests,itemRunContext,accumulation),appendContextPreflightWarning(options,accumulation);const outcome=resolveTestAllOutcome({options,accumulation,failOnEmptyTestRunTriggered});return emitTestAllProgress(options,`end status=${outcome.ok?"passed":"failed"} items=${prepared.filteredItems.length} linked_tests=${prepared.linkedTests} passed=${accumulation.passed} failed=${accumulation.failed} skipped=${accumulation.skipped}`),buildTestAllResult({ok:outcome.ok,filteredItems:prepared.filteredItems,linkedTests:prepared.linkedTests,accumulation,failOnSkippedTriggered:outcome.failOnSkippedTriggered,failOnEmptyTestRunTriggered})},_testOnlyTestAll={buildLinkedTestKey,formatTrackingError};export{_testOnlyTestAll,runTestAll};
 //# sourceMappingURL=batch.js.map

package/dist/sdk/test/command-args.d.ts

@@ -0,0 +1,4 @@
+/** Serialize one item test run with its mutations, selectors, context and explicitly supplied trust flags. */
+export declare function buildBackgroundTestCommandArgs(id: string, options: Record<string, unknown>): string[];
+/** Serialize a tracker-wide test run with status filters and shared execution policy. */
+export declare function buildBackgroundTestAllCommandArgs(options: Record<string, unknown>): string[];

package/dist/sdk/test/command-args.js

@@ -0,0 +1,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]="201134b5-01e8-55ae-a099-137b9b6fae92")}catch{}})();function pushOptionalValueFlag(args,flag,value){if(typeof value!="string")return;const trimmed=value.trim();trimmed.length!==0&&args.push(flag,trimmed)}function pushOptionalBooleanFlag(args,flag,value){value===!0&&args.push(flag)}function pushRepeatableValueFlag(args,flag,values){if(Array.isArray(values))for(const value of values){if(typeof value!="string")continue;const trimmed=value.trim();trimmed.length!==0&&args.push(flag,trimmed)}}function buildBackgroundTestCommandArgs(id,options){const args=["test",id,"--run","--json","--progress"];return pushRepeatableValueFlag(args,"--add",options.add),pushRepeatableValueFlag(args,"--add-json",options.addJson),pushRepeatableValueFlag(args,"--remove",options.remove),pushRepeatableValueFlag(args,"--remove-index",Array.isArray(options.removeIndex)?options.removeIndex.map(index=>typeof index=="number"?String(index):index):options.removeIndex),pushOptionalValueFlag(args,"--match",options.match),pushOptionalValueFlag(args,"--only-index",typeof options.onlyIndex=="number"?String(options.onlyIndex):options.onlyIndex),pushOptionalBooleanFlag(args,"--only-last",options.onlyLast),pushRepeatableValueFlag(args,"--measure",options.measure),pushOptionalValueFlag(args,"--metric-below",options.metricBelow),pushOptionalValueFlag(args,"--metric-diff",options.metricDiff),pushSharedBackgroundTestCommandArgs(args,options),pushOptionalValueFlag(args,"--author",options.author),pushOptionalValueFlag(args,"--message",options.message),pushOptionalBooleanFlag(args,"--force",options.force),args}function pushSharedBackgroundTestCommandArgs(args,options){pushOptionalValueFlag(args,"--timeout",options.timeout),pushRepeatableValueFlag(args,"--env-set",options.envSet),pushRepeatableValueFlag(args,"--env-clear",options.envClear),pushOptionalBooleanFlag(args,"--shared-host-safe",options.sharedHostSafe),pushOptionalValueFlag(args,"--pm-context",options.pmContext),pushOptionalBooleanFlag(args,"--override-linked-pm-context",options.overrideLinkedPmContext),pushOptionalValueFlag(args,"--workspace-context",options.workspaceContext),pushOptionalBooleanFlag(args,"--override-linked-workspace-context",options.overrideLinkedWorkspaceContext),pushOptionalBooleanFlag(args,"--allow-untrusted-linked-tests",options.allowUntrustedLinkedTests),pushOptionalBooleanFlag(args,"--fail-on-context-mismatch",options.failOnContextMismatch),pushOptionalBooleanFlag(args,"--fail-on-skipped",options.failOnSkipped),pushOptionalBooleanFlag(args,"--fail-on-empty-test-run",options.failOnEmptyTestRun),pushOptionalBooleanFlag(args,"--require-assertions-for-pm",options.requireAssertionsForPm),pushOptionalBooleanFlag(args,"--check-context",options.checkContext),pushOptionalBooleanFlag(args,"--auto-pm-context",options.autoPmContext)}function buildBackgroundTestAllCommandArgs(options){const args=["test-all","--json","--progress"];return pushOptionalValueFlag(args,"--status",options.status),pushOptionalValueFlag(args,"--limit",options.limit),pushOptionalValueFlag(args,"--offset",options.offset),pushSharedBackgroundTestCommandArgs(args,options),args}export{buildBackgroundTestAllCommandArgs,buildBackgroundTestCommandArgs};
+//# sourceMappingURL=command-args.js.map

package/dist/sdk/test/entry.d.ts

@@ -1,3 +1,6 @@
+import type { LinkedTest } from "../../types/index.js";
+/** Refuse an unbound tracker context before a linked-test mutation can persist it. */
+export declare function assertLinkedTestContext(test: LinkedTest): void;
 /** Public contract for structured linked test keys, shared by SDK and presentation-layer consumers. */
 export declare const STRUCTURED_LINKED_TEST_KEYS: readonly ["command", "cmd", "path", "scope", "timeout", "timeout_seconds", "pm_context_mode", "workspace_context_mode", "env_set", "env_clear", "shared_host_safe", "assert_stdout_contains", "assert_stdout_regex", "assert_stderr_contains", "assert_stderr_regex", "assert_stdout_min_lines", "assert_json_field_equals", "assert_json_field_gte", "note"];
 /** Classify linked-test plaintext through the shared structured-entry grammar. */

package/dist/sdk/test/entry.js

@@ -1,2 +1,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]="b968be78-8489-5735-8f95-8e38a36e160a")}catch{}})();import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{looksLikeStructuredKeyValueEntry}from"../../core/item/parse.js";const STRUCTURED_LINKED_TEST_KEYS=["command","cmd","path","scope","timeout","timeout_seconds","pm_context_mode","workspace_context_mode","env_set","env_clear","shared_host_safe","assert_stdout_contains","assert_stdout_regex","assert_stderr_contains","assert_stderr_regex","assert_stdout_min_lines","assert_json_field_equals","assert_json_field_gte","note"],STRUCTURED_LINKED_TEST_KEY_SET=new Set(STRUCTURED_LINKED_TEST_KEYS);function looksLikeStructuredLinkedTestEntry(raw){return looksLikeStructuredKeyValueEntry(raw,STRUCTURED_LINKED_TEST_KEYS)}function normalizeStructuredLinkedTestEntry(kv,optionName){const normalizedKv={},unknownKeys=[];for(const[key,value]of Object.entries(kv)){const normalizedKey=key.toLowerCase();if(!STRUCTURED_LINKED_TEST_KEY_SET.has(normalizedKey)){unknownKeys.push(key);continue}if(Object.hasOwn(normalizedKv,normalizedKey))throw new PmCliError(`${optionName} provides key "${key}" more than once after case normalization`,EXIT_CODE.USAGE);normalizedKv[normalizedKey]=value}if(unknownKeys.length>0)throw new PmCliError(`${optionName} does not recognize key${unknownKeys.length>1?"s":""} ${unknownKeys.map(key=>`"${key}"`).join(", ")}. Allowed keys: ${STRUCTURED_LINKED_TEST_KEYS.join(", ")}.`,EXIT_CODE.USAGE);if(normalizedKv.cmd!==void 0){if(normalizedKv.command!==void 0&&normalizedKv.command.trim()!==normalizedKv.cmd.trim())throw new PmCliError(`${optionName} command and cmd must match when both are provided`,EXIT_CODE.USAGE);const{cmd,...rest}=normalizedKv;return{...rest,command:rest.command??cmd}}return normalizedKv}export{STRUCTURED_LINKED_TEST_KEYS,looksLikeStructuredLinkedTestEntry,normalizeStructuredLinkedTestEntry};
+(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]="4025e3fb-f2f2-57f1-a981-5bbb2381fe67")}catch{}})();import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{looksLikeStructuredKeyValueEntry}from"../../core/item/parse.js";import{renderPmCommand}from"../command-line.js";function assertLinkedTestContext(test){if(!(test.pm_context_mode!=="none"||test.workspace_context_mode==="isolated"||test.workspace_context_mode==="snapshot"))throw new PmCliError("pm_context_mode=none requires workspace_context_mode=isolated or snapshot so implicit tracker discovery cannot reach the source workspace.",EXIT_CODE.USAGE,{code:"linked_test_context_invalid",required:"Set workspace_context_mode to isolated or snapshot when pm_context_mode is none.",examples:[renderPmCommand(["test","<id>","--add-json",JSON.stringify({command:test.command,pm_context_mode:"none",workspace_context_mode:"isolated"})])]})}const STRUCTURED_LINKED_TEST_KEYS=["command","cmd","path","scope","timeout","timeout_seconds","pm_context_mode","workspace_context_mode","env_set","env_clear","shared_host_safe","assert_stdout_contains","assert_stdout_regex","assert_stderr_contains","assert_stderr_regex","assert_stdout_min_lines","assert_json_field_equals","assert_json_field_gte","note"],STRUCTURED_LINKED_TEST_KEY_SET=new Set(STRUCTURED_LINKED_TEST_KEYS);function looksLikeStructuredLinkedTestEntry(raw){return looksLikeStructuredKeyValueEntry(raw,STRUCTURED_LINKED_TEST_KEYS)}function normalizeStructuredLinkedTestEntry(kv,optionName){const normalizedKv={},unknownKeys=[];for(const[key,value]of Object.entries(kv)){const normalizedKey=key.toLowerCase();if(!STRUCTURED_LINKED_TEST_KEY_SET.has(normalizedKey)){unknownKeys.push(key);continue}if(Object.hasOwn(normalizedKv,normalizedKey))throw new PmCliError(`${optionName} provides key "${key}" more than once after case normalization`,EXIT_CODE.USAGE);normalizedKv[normalizedKey]=value}if(unknownKeys.length>0)throw new PmCliError(`${optionName} does not recognize key${unknownKeys.length>1?"s":""} ${unknownKeys.map(key=>`"${key}"`).join(", ")}. Allowed keys: ${STRUCTURED_LINKED_TEST_KEYS.join(", ")}.`,EXIT_CODE.USAGE);if(normalizedKv.cmd!==void 0){if(normalizedKv.command!==void 0&&normalizedKv.command.trim()!==normalizedKv.cmd.trim())throw new PmCliError(`${optionName} command and cmd must match when both are provided`,EXIT_CODE.USAGE);const{cmd,...rest}=normalizedKv;return{...rest,command:rest.command??cmd}}return normalizedKv}export{STRUCTURED_LINKED_TEST_KEYS,assertLinkedTestContext,looksLikeStructuredLinkedTestEntry,normalizeStructuredLinkedTestEntry};
 //# sourceMappingURL=entry.js.map

package/dist/sdk/test/execution-receipts.d.ts

@@ -1,9 +1,9 @@
 /** Detect explicit empty-run summaries even when another output line reports a positive count. */
 export declare function detectEmptyLinkedTestRun(stdout: string, stderr: string): {
-    code: string;
+code: string;
 } | null;
 /** Find the first supported positive execution summary, preferring stdout over stderr. */
 export declare function findLinkedTestExecutionReceipt(stdout: string, stderr: string): {
-    code: string;
-    stream: "stdout" | "stderr";
+code: string;
+stream: "stdout" | "stderr";
 } | undefined;