@unbrained/pm-cli 2026.10.12 → 2026.10.14

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/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;