@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/lifecycle/append.js

@@ -1,54 +1,3 @@
-/**
- * @module cli/commands/append
- *
- * Implements the pm append command surface and its agent-facing runtime behavior.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b4b1f63b-12f9-574c-8e92-a5cc9c6178c1")}catch(e){}}();
-import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { EXIT_CODE, PmCliError, resolveAuthor, toItemRecord, createStdinTokenResolver, shouldResolveMutationStdinTokenField, mutateItem, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
-/** Implements run append for the public runtime surface of this module. */
-export async function runAppend(id, options, global) {
-    if (options.body === undefined) {
-        throw new PmCliError("Missing required --body text", EXIT_CODE.USAGE);
-    }
-    const stdinResolver = createStdinTokenResolver();
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const author = resolveAuthor(options.author, settings.author_default);
-    // options.body is guaranteed defined by the guard above, so resolveValue returns a defined string.
-    const bodyInput = await stdinResolver.resolveValue(options.body, "--body", shouldResolveMutationStdinTokenField(options, "body"));
-    const appended = bodyInput.trim();
-    if (appended.length === 0) {
-        throw new PmCliError("--body text cannot be empty; append requires non-blank content and empty appends would only rewrite updated_at.", EXIT_CODE.USAGE, {
-            code: "append_empty_body",
-            required: "Provide non-empty body text positionally, via --body, or with - for stdin.",
-            examples: [
-                'pm append pm-a1b2 --body "Progress note"',
-                "pm append pm-a1b2 --body -",
-            ],
-        });
-    }
-    const result = await mutateItem({
-        pmRoot,
-        settings,
-        id,
-        op: "append",
-        author,
-        message: options.message,
-        force: options.force,
-        mutate(document) {
-            const spacer = document.body.trim().length > 0 ? "\n\n" : "";
-            document.body = `${document.body.trimEnd()}${spacer}${appended}\n`;
-            return { changedFields: ["body"] };
-        },
-    });
-    return {
-        item: toItemRecord(result.item),
-        appended,
-        changed_fields: result.changedFields,
-    };
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="663579ae-aebb-524c-81c9-9aed44e40f35")}catch(e2){}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{EXIT_CODE,PmCliError,resolveAuthor,toItemRecord,createStdinTokenResolver,shouldResolveMutationStdinTokenField,mutateItem,resolvePmRoot,readSettings}from"../runtime-primitives.js";async function runAppend(id,options,global2){if(options.body===void 0){throw new PmCliError("Missing required --body text",EXIT_CODE.USAGE)}const stdinResolver=createStdinTokenResolver();const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const author=resolveAuthor(options.author,settings.author_default);const bodyInput=await stdinResolver.resolveValue(options.body,"--body",shouldResolveMutationStdinTokenField(options,"body"));const appended=bodyInput.trim();if(appended.length===0){throw new PmCliError("--body text cannot be empty; append requires non-blank content and empty appends would only rewrite updated_at.",EXIT_CODE.USAGE,{code:"append_empty_body",required:"Provide non-empty body text positionally, via --body, or with - for stdin.",examples:['pm append pm-a1b2 --body "Progress note"',"pm append pm-a1b2 --body -"]})}const result=await mutateItem({pmRoot,settings,id,op:"append",author,message:options.message,force:options.force,mutate(document){const spacer=document.body.trim().length>0?"\n\n":"";document.body=`${document.body.trimEnd()}${spacer}${appended}
+`;return{changedFields:["body"]}}});return{item:toItemRecord(result.item),appended,changed_fields:result.changedFields}}export{runAppend};
 //# sourceMappingURL=append.js.map
-//# debugId=b4b1f63b-12f9-574c-8e92-a5cc9c6178c1

package/dist/sdk/lifecycle/claim.d.ts

@@ -6,6 +6,8 @@ export declare const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
 export interface ClaimResult {
     /** Value that configures or reports item for this contract. */
     item: Record<string, unknown>;
+    /** Metadata fields changed by this claim; empty for an idempotent or skipped claim. */
+    changed_fields?: string[];
     /** Value that configures or reports claimed by for this contract. */
     claimed_by: string;
     /** Value that configures or reports previous assignee for this contract. */

package/dist/sdk/lifecycle/claim.js

@@ -1,243 +1,2 @@
-/**
- * @module cli/commands/claim
- *
- * Implements the pm claim command surface and its agent-facing runtime behavior.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a4d95016-05b9-5272-8044-2649da644e98")}catch(e){}}();
-import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { resolveRuntimeStatusRegistry, statusIsTerminal, EXIT_CODE, PmCliError, toItemRecord, mutateItem, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, normalizeStatusForRegistry, } from "../runtime-primitives.js";
-import { wrapOwnershipConflict } from "../annotations.js";
-import { describeItemOwnershipConflict } from "../ownership-source.js";
-import { runNext, } from "../query/next.js";
-import { recordClaimSemanticAttribution, recordReleaseSemanticAttribution, } from "../context/semantic-session-attribution.js";
-/** Stable warning/error code for an exhausted atomic next-work walk. */
-export const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
-/** Returns whether a failed claim lost the atomic test-and-set race. */
-export function isAlreadyClaimedError(error) {
-    if (!(error instanceof Error) || error.name !== "PmCliError") {
-        return false;
-    }
-    const context = error.context;
-    return (typeof context === "object" &&
-        context !== null &&
-        "code" in context &&
-        context.code === "already_claimed_by");
-}
-/** Implements run claim for the public runtime surface of this module. */
-export async function runClaim(id, force, global, options = {}) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-    const author = resolveAuthor(options.author, settings.author_default);
-    const claimPrincipal = resolveClaimPrincipal(author);
-    let previousAssignee = null;
-    let skipped = false;
-    const mutationWarnings = [];
-    const result = await mutateItem({
-        pmRoot,
-        settings,
-        id,
-        op: "claim",
-        author,
-        message: options.message,
-        force,
-        skipNoop: true,
-        async mutate(document) {
-            const currentAssignee = document.metadata.assignee;
-            const currentAssigneeText = currentAssignee ?? "";
-            const currentClaimPrincipal = document.metadata.claim_principal?.trim() || currentAssigneeText;
-            previousAssignee =
-                currentAssigneeText.trim().length > 0 ? currentAssigneeText : null;
-            if (statusIsTerminal(document.metadata.status, statusRegistry) &&
-                !force) {
-                throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`, EXIT_CODE.CONFLICT);
-            }
-            const heldByOther = previousAssignee !== null && currentClaimPrincipal !== claimPrincipal;
-            if (heldByOther) {
-                if (options.ifAvailable === true) {
-                    skipped = true;
-                    mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`);
-                    return { changedFields: [] };
-                }
-                if (!force) {
-                    const ownershipPhrase = await describeItemOwnershipConflict(pmRoot, document.metadata.id, currentAssigneeText);
-                    throw new PmCliError(`Item ${document.metadata.id} is already ${ownershipPhrase}. Use --force to take over, or --if-available to skip without failing.`, EXIT_CODE.CONFLICT, {
-                        code: "already_claimed_by",
-                        why: "Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",
-                        nextSteps: [
-                            "Run pm next to pick a different unclaimed item.",
-                            "Re-run with --if-available to treat a held item as a no-op skip.",
-                            "Re-run with --force only when taking over the item is coordinated.",
-                        ],
-                    });
-                }
-                mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`);
-            }
-            document.metadata.assignee = author;
-            document.metadata.claim_principal = claimPrincipal;
-            return {
-                changedFields: ["assignee", "claim_principal"],
-                warnings: mutationWarnings,
-            };
-        },
-    });
-    if (!skipped) {
-        await recordClaimSemanticAttribution({
-            pmRoot,
-            settings,
-            principal: claimPrincipal,
-            itemId: result.item.id,
-        });
-    }
-    return {
-        item: toItemRecord(result.item),
-        claimed_by: skipped && previousAssignee !== null ? previousAssignee : author,
-        previous_assignee: previousAssignee,
-        forced: force,
-        ...(skipped ? { skipped: true } : {}),
-        ...(mutationWarnings.length > 0 ? { warnings: mutationWarnings } : {}),
-    };
-}
-/** Selects ranked actionable work and claims the first candidate still available under the item lock. Conflicts caused by parallel claimers advance to the next candidate instead of returning a thundering-herd failure. */
-export async function runClaimNext(force, global, options = {}, nextOptions = {}) {
-    const maxAttempts = parseClaimNextAttempts(options.maxAttempts);
-    const settings = await readSettings(resolvePmRoot(process.cwd(), global.path));
-    const claimOptions = {
-        ...options,
-        author: resolveAuthor(options.author, settings.author_default),
-    };
-    const next = await runNext({
-        ...nextOptions,
-        callerAuthor: claimOptions.author,
-        limit: String(maxAttempts),
-    }, global);
-    const recommendations = [next.recommended, ...next.ready]
-        .filter((entry) => entry !== null)
-        .map((entry) => ({
-        ...entry,
-        reasons: "reasons" in entry ? entry.reasons : ["ranked ready candidate"],
-    }));
-    return claimNextFromRecommendations(recommendations.slice(0, maxAttempts), force, global, claimOptions);
-}
-/** Parses the bounded candidate walk used by `claim --next`. */
-export function parseClaimNextAttempts(raw) {
-    if (raw === undefined)
-        return 10;
-    const parsed = Number(raw);
-    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 100) {
-        throw new PmCliError("--max-attempts must be an integer from 1 to 100", EXIT_CODE.USAGE);
-    }
-    return parsed;
-}
-/** Claims the first still-available row from a pre-ranked recommendation set. */
-export async function claimNextFromRecommendations(recommendations, force, global, options = {}, claimRunner = runClaim) {
-    let attempts = 0;
-    for (const recommendation of recommendations) {
-        attempts += 1;
-        try {
-            const claimed = await claimRunner(recommendation.id, force, global, options);
-            const result = {
-                ...claimed,
-                recommendation,
-                attempts,
-                available: true,
-            };
-            if (!claimed.skipped)
-                return result;
-        }
-        catch (error) {
-            if (!isAlreadyClaimedError(error))
-                throw error;
-        }
-    }
-    if (options.ifAvailable === true) {
-        return {
-            available: false,
-            item: null,
-            claimed_by: resolveAuthor(options.author, ""),
-            previous_assignee: null,
-            forced: force,
-            skipped: true,
-            recommendation: null,
-            attempts,
-            warnings: [NO_AVAILABLE_NEXT_ITEM_CODE],
-        };
-    }
-    const noCandidatesMatched = attempts === 0;
-    throw new PmCliError(noCandidatesMatched
-        ? "No actionable items matched the selection filters"
-        : "No actionable item remained available to claim", noCandidatesMatched ? EXIT_CODE.NOT_FOUND : EXIT_CODE.CONFLICT, {
-        code: NO_AVAILABLE_NEXT_ITEM_CODE,
-        why: noCandidatesMatched
-            ? "No ready items matched the specified filters or selection criteria."
-            : "Every ranked candidate was claimed by another agent before this atomic selection completed.",
-        nextSteps: [
-            noCandidatesMatched
-                ? "Verify the filters or run pm next to inspect all ready work."
-                : "Run pm claim --next again to refresh the ranked candidate set.",
-        ],
-    });
-}
-/** Implements run release for the public runtime surface of this module. */
-export async function runRelease(id, force, global, options = {}) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const author = resolveAuthor(options.author, settings.author_default);
-    const claimPrincipal = resolveClaimPrincipal(author);
-    const ownershipReleaseBypass = options.ownershipReleaseBypass === true;
-    let previousAssignee = null;
-    let result;
-    try {
-        result = await mutateItem({
-            pmRoot,
-            settings,
-            id,
-            op: "release",
-            author,
-            message: options.message,
-            force,
-            bypassAssigneeConflict: ownershipReleaseBypass,
-            mutate(document) {
-                previousAssignee = document.metadata.assignee ?? null;
-                if (!previousAssignee && !document.metadata.claim_principal) {
-                    return { changedFields: [] };
-                }
-                delete document.metadata.assignee;
-                delete document.metadata.claim_principal;
-                return { changedFields: ["assignee", "claim_principal"] };
-            },
-        });
-    }
-    catch (error) {
-        wrapOwnershipConflict(error, {
-            required: "For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",
-            examples: ['pm release pm-a1b2 --author "reviewer" --force'],
-            nextSteps: [
-                "Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.",
-                "Use --force only when an explicit override is approved for broader ownership conflicts.",
-            ],
-        });
-    }
-    await recordReleaseSemanticAttribution({
-        pmRoot,
-        principal: claimPrincipal,
-        itemId: result.item.id,
-    });
-    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-    const stillInProgress = normalizeStatusForRegistry(result.item.status, statusRegistry) === normalizeStatusForRegistry(statusRegistry.in_progress_status, statusRegistry);
-    return {
-        item: toItemRecord(result.item),
-        released_by: author,
-        previous_assignee: previousAssignee,
-        forced: force,
-        ...(stillInProgress ? {
-            warnings: ["released_unclaimed_in_progress"],
-            suggestions: [`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm pause-task ${result.item.id} to move it to ${statusRegistry.open_status}.`],
-        } : {}),
-    };
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="90cfbd3e-1656-54cc-a9f8-66bffe14685f")}catch(e2){}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolveRuntimeStatusRegistry,statusIsTerminal,EXIT_CODE,PmCliError,toItemRecord,mutateItem,resolvePmRoot,readSettings,resolveAuthor,resolveClaimPrincipal,normalizeStatusForRegistry}from"../runtime-primitives.js";import{wrapOwnershipConflict}from"../annotations.js";import{describeItemOwnershipConflict}from"../ownership-source.js";import{runNext}from"../query/next.js";import{recordClaimSemanticAttribution,recordReleaseSemanticAttribution}from"../context/semantic-session-attribution.js";const NO_AVAILABLE_NEXT_ITEM_CODE="no_available_next_item";function isAlreadyClaimedError(error){if(!(error instanceof Error)||error.name!=="PmCliError"){return false}const context=error.context;return typeof context==="object"&&context!==null&&"code"in context&&context.code==="already_claimed_by"}async function runClaim(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const statusRegistry=resolveRuntimeStatusRegistry(settings.schema);const author=resolveAuthor(options.author,settings.author_default);const claimPrincipal=resolveClaimPrincipal(author);let previousAssignee=null;let skipped=false;const mutationWarnings=[];const result=await mutateItem({pmRoot,settings,id,op:"claim",author,message:options.message,force,skipNoop:true,async mutate(document){const currentAssignee=document.metadata.assignee;const currentAssigneeText=currentAssignee??"";const currentClaimPrincipal=document.metadata.claim_principal?.trim()||currentAssigneeText;previousAssignee=currentAssigneeText.trim().length>0?currentAssigneeText:null;if(statusIsTerminal(document.metadata.status,statusRegistry)&&!force){throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`,EXIT_CODE.CONFLICT)}const heldByOther=previousAssignee!==null&&currentClaimPrincipal!==claimPrincipal;if(heldByOther){if(options.ifAvailable===true){skipped=true;mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`);return{changedFields:[]}}if(!force){const ownershipPhrase=await describeItemOwnershipConflict(pmRoot,document.metadata.id,currentAssigneeText);throw new PmCliError(`Item ${document.metadata.id} is already ${ownershipPhrase}. Use --force to take over, or --if-available to skip without failing.`,EXIT_CODE.CONFLICT,{code:"already_claimed_by",why:"Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",nextSteps:["Run pm next to pick a different unclaimed item.","Re-run with --if-available to treat a held item as a no-op skip.","Re-run with --force only when taking over the item is coordinated."]})}mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`)}const ownership={assignee:author,claim_principal:claimPrincipal};const changedFields=["assignee","claim_principal"].filter(field=>document.metadata[field]!==ownership[field]);Object.assign(document.metadata,ownership);return{changedFields,warnings:mutationWarnings}}});if(!skipped){await recordClaimSemanticAttribution({pmRoot,settings,principal:claimPrincipal,itemId:result.item.id})}return{item:toItemRecord(result.item),changed_fields:result.changedFields,claimed_by:skipped&&previousAssignee!==null?previousAssignee:author,previous_assignee:previousAssignee,forced:force,...skipped?{skipped:true}:{},...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}async function runClaimNext(force,global2,options={},nextOptions={}){const maxAttempts=parseClaimNextAttempts(options.maxAttempts);const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path));const claimOptions={...options,author:resolveAuthor(options.author,settings.author_default)};const next=await runNext({...nextOptions,callerAuthor:claimOptions.author,limit:String(maxAttempts)},global2);const recommendations=[next.recommended,...next.ready].filter(entry=>entry!==null).map(entry=>({...entry,reasons:"reasons"in entry?entry.reasons:["ranked ready candidate"]}));return claimNextFromRecommendations(recommendations.slice(0,maxAttempts),force,global2,claimOptions)}function parseClaimNextAttempts(raw){if(raw===void 0)return 10;const parsed=Number(raw);if(!Number.isSafeInteger(parsed)||parsed<1||parsed>100){throw new PmCliError("--max-attempts must be an integer from 1 to 100",EXIT_CODE.USAGE)}return parsed}async function claimNextFromRecommendations(recommendations,force,global2,options={},claimRunner=runClaim){let attempts=0;for(const recommendation of recommendations){attempts+=1;try{const claimed=await claimRunner(recommendation.id,force,global2,options);const result={...claimed,recommendation,attempts,available:true};if(!claimed.skipped)return result}catch(error){if(!isAlreadyClaimedError(error))throw error}}if(options.ifAvailable===true){return{available:false,item:null,claimed_by:resolveAuthor(options.author,""),previous_assignee:null,forced:force,skipped:true,recommendation:null,attempts,warnings:[NO_AVAILABLE_NEXT_ITEM_CODE]}}const noCandidatesMatched=attempts===0;throw new PmCliError(noCandidatesMatched?"No actionable items matched the selection filters":"No actionable item remained available to claim",noCandidatesMatched?EXIT_CODE.NOT_FOUND:EXIT_CODE.CONFLICT,{code:NO_AVAILABLE_NEXT_ITEM_CODE,why:noCandidatesMatched?"No ready items matched the specified filters or selection criteria.":"Every ranked candidate was claimed by another agent before this atomic selection completed.",nextSteps:[noCandidatesMatched?"Verify the filters or run pm next to inspect all ready work.":"Run pm claim --next again to refresh the ranked candidate set."]})}async function runRelease(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const author=resolveAuthor(options.author,settings.author_default);const claimPrincipal=resolveClaimPrincipal(author);const ownershipReleaseBypass=options.ownershipReleaseBypass===true;let previousAssignee=null;let result;try{result=await mutateItem({pmRoot,settings,id,op:"release",author,message:options.message,force,bypassAssigneeConflict:ownershipReleaseBypass,mutate(document){previousAssignee=document.metadata.assignee??null;if(!previousAssignee&&!document.metadata.claim_principal){return{changedFields:[]}}delete document.metadata.assignee;delete document.metadata.claim_principal;return{changedFields:["assignee","claim_principal"]}}})}catch(error){wrapOwnershipConflict(error,{required:"For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",examples:['pm release pm-a1b2 --author "reviewer" --force'],nextSteps:["Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.","Use --force only when an explicit override is approved for broader ownership conflicts."]})}await recordReleaseSemanticAttribution({pmRoot,principal:claimPrincipal,itemId:result.item.id});const statusRegistry=resolveRuntimeStatusRegistry(settings.schema);const stillInProgress=normalizeStatusForRegistry(result.item.status,statusRegistry)===normalizeStatusForRegistry(statusRegistry.in_progress_status,statusRegistry);return{item:toItemRecord(result.item),released_by:author,previous_assignee:previousAssignee,forced:force,...stillInProgress?{warnings:["released_unclaimed_in_progress"],suggestions:[`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm pause-task ${result.item.id} to move it to ${statusRegistry.open_status}.`]}:{}}}export{NO_AVAILABLE_NEXT_ITEM_CODE,claimNextFromRecommendations,isAlreadyClaimedError,parseClaimNextAttempts,runClaim,runClaimNext,runRelease};
 //# sourceMappingURL=claim.js.map
-//# debugId=a4d95016-05b9-5272-8044-2649da644e98