@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/structured-mutations.js

@@ -1,581 +1,2 @@
-/**
- * @module sdk/structured-mutations
- *
- * Parses agent-authored JSON mutation payloads into the public atomic item
- * transaction contract and normalizes full item documents for CLI round trips.
- */
-
-!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]="3f348972-0c8f-52da-abeb-46690df967d8")}catch(e){}}();
-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";
-const MUTATION_ROW_KEYS = ["op", "id", "reason", "options"];
-const REFERENCED_MUTATION_ROW_KEYS = [
-    ...MUTATION_ROW_KEYS,
-    "ref",
-];
-const MUTATION_DOCUMENT_KEYS = ["schema_version", "mutations"];
-const MUTATION_REFERENCE_SOURCE = "[a-z][a-z0-9._-]{0,63}";
-const MUTATION_REFERENCE_PATTERN = new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`, "u");
-const MUTATION_DEPENDENCY_REFERENCE_PATTERN = new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`, "gu");
-const flagToOptionKey = (flag) => flag
-    .slice(2)
-    .replaceAll(/-([a-z])/gu, (_match, letter) => letter.toUpperCase());
-const ITEM_ENVELOPE_KEYS = [
-    "item",
-    "linked",
-    "schedule",
-    "claim_state",
-    "children",
-    "omission_receipt",
-    "row_contract",
-    "context_intent",
-];
-const READ_ONLY_ITEM_KEYS = new Set([
-    "created_at",
-    "updated_at",
-    "closed_at",
-    "version",
-    "format_version",
-    "path",
-    "author",
-    "collection_counts",
-    "notes_count",
-    "tests_count",
-]);
-const UPDATE_READ_ONLY_ITEM_KEYS = new Set([
-    ...READ_ONLY_ITEM_KEYS,
-    "completed_at",
-    "id",
-]);
-const 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",
-]);
-const 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)),
-};
-/** Validate and normalize atomic transaction controls at every transport boundary. */
-export function parseAtomicMutationControls(value) {
-    const controls = {};
-    const compensation = value.createCompensation;
-    if (compensation !== undefined) {
-        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 === undefined)
-            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 false;
-    }
-    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);
-        if (distance !== null && (best === undefined || distance < best.distance)) {
-            best = { key: candidate, distance };
-        }
-    }
-    return best?.key;
-}
-function unknownKeyError(scope, key, candidates) {
-    const suggestion = nearestKey(key, candidates);
-    return new PmCliError(suggestion === undefined
-        ? `${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 === undefined
-                ? `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 === undefined)
-        return undefined;
-    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);
-    const { 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 === undefined
-                ? {}
-                : { options: options }),
-        };
-    }
-    if (op === "release") {
-        return {
-            op,
-            id: normalizedId,
-            ...(options === undefined
-                ? {}
-                : { options: options }),
-        };
-    }
-    if (!isPlainObject(options)) {
-        throw new PmCliError(`Mutation ${index + 1} ${op} requires an options object.`, EXIT_CODE.USAGE);
-    }
-    return {
-        op,
-        id: normalizedId,
-        options: options,
-    };
-}
-/** Parse a JSON array, or an object containing `mutations`, into an atomic mutation batch. */
-export function parseItemMutationBatch(input) {
-    const parsed = parseJsonValue(input, "Mutation batch");
-    const rows = Array.isArray(parsed)
-        ? parsed
-        : isPlainObject(parsed) && Array.isArray(parsed.mutations)
-            ? parsed.mutations
-            : undefined;
-    if (rows === undefined || 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);
-        if (mutation.options !== undefined) {
-            preserveMutationStdinTokenLiterals(mutation.options);
-        }
-        return mutation;
-    });
-}
-function deriveReferencedItemId(transactionId, reference, idPrefix) {
-    const digest = crypto
-        .createHash("sha256")
-        .update(transactionId)
-        .update("\0")
-        .update(reference)
-        .digest("hex");
-    const 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);
-    const resolved = references[reference];
-    if (resolved === undefined) {
-        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 === undefined) {
-            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) {
-    if (typeof value !== "string")
-        return [];
-    if (value.startsWith("@"))
-        return [value.slice(1)];
-    return [...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)]
-        .map((match) => match[1])
-        .filter((reference) => reference !== undefined);
-}
-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 : {};
-        const dependencies = Array.isArray(mutationOptions.dep)
-            ? mutationOptions.dep
-            : mutationOptions.dep === undefined
-                ? []
-                : [mutationOptions.dep];
-        graph.set(row.ref, [mutationOptions.parent, mutationOptions.blockedBy, ...dependencies]
-            .flatMap(referencedAliases));
-    }
-    const visiting = new Set();
-    const visited = new Set();
-    const visit = (reference) => {
-        if (visiting.has(reference)) {
-            throw new PmCliError(`Mutation reference cycle includes "@${reference}".`, EXIT_CODE.USAGE);
-        }
-        if (visited.has(reference))
-            return;
-        visiting.add(reference);
-        for (const dependency of graph.get(reference)) {
-            if (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");
-    const 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 !== undefined &&
-        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 === undefined)
-            continue;
-        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] !== undefined) {
-            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;
-}
-/**
- * Resolve a versioned heterogeneous mutation document. Create rows may declare
- * a unique `ref`; omitted ids are derived deterministically from the stable
- * transaction id, and `@ref` forward references are supported in target ids,
- * parent/blocked-by options, and dependency entries.
- */
-export function resolveItemMutationDocument(input, options) {
-    const rows = parseMutationDocumentRows(input);
-    const references = collectMutationReferences(rows, options);
-    assertAcyclicCreateReferences(rows);
-    const resolvedRows = rows.map((row) => {
-        const resolved = { ...row };
-        const reference = typeof resolved.ref === "string" ? resolved.ref : undefined;
-        delete resolved.ref;
-        if (reference !== undefined) {
-            resolved.id = references[reference];
-        }
-        else {
-            resolved.id = replaceExactMutationReference(resolved.id, references);
-        }
-        if (isPlainObject(resolved.options)) {
-            const mutationOptions = { ...resolved.options };
-            for (const key of ["parent", "blockedBy"]) {
-                if (mutationOptions[key] !== undefined) {
-                    mutationOptions[key] = replaceExactMutationReference(mutationOptions[key], references);
-                }
-            }
-            if (Array.isArray(mutationOptions.dep)) {
-                mutationOptions.dep = mutationOptions.dep.map((entry) => replaceDependencyReference(entry, references));
-            }
-            else if (mutationOptions.dep !== undefined) {
-                mutationOptions.dep = replaceDependencyReference(mutationOptions.dep, references);
-            }
-            resolved.options = mutationOptions;
-        }
-        return resolved;
-    });
-    const mutations = parseItemMutationBatch(JSON.stringify(resolvedRows));
-    const 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] !== undefined && 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 === undefined)
-        return undefined;
-    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) {
-    if (key === "tags" &&
-        Array.isArray(value) &&
-        value.every((entry) => typeof entry === "string")) {
-        return JSON.stringify(value);
-    }
-    if (typeof value === "number" || typeof value === "boolean") {
-        return String(value);
-    }
-    return value;
-}
-function appendFacetOptions(target, source, skipPersistedAnnotations = false) {
-    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];
-        const serialized = serializeObjectArray(skipPersistedAnnotations &&
-            ["comments", "notes", "learnings"].includes(sourceKey) &&
-            Array.isArray(sourceValue)
-            ? sourceValue.filter((entry) => !isPlainObject(entry) || entry.created_at === undefined)
-            : sourceValue, keys, sourceKey);
-        if (serialized !== undefined && 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]) === undefined &&
-            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) {
-    const readOnlyKeys = mode === "update" ? UPDATE_READ_ONLY_ITEM_KEYS : READ_ONLY_ITEM_KEYS;
-    if (readOnlyKeys.has(key))
-        return;
-    if (!ITEM_FIELD_KEYS.has(key)) {
-        const suggestion = nearestKey(key, [...ITEM_FIELD_KEYS]);
-        if (suggestion !== undefined)
-            throw unknownKeyError("item document", key, [...ITEM_FIELD_KEYS]);
-        const fields = Array.isArray(documentOptions.field)
-            ? documentOptions.field
-            : [];
-        fields.push(serializePairs({
-            key,
-            value: typeof value === "string" ? value : JSON.stringify(value),
-        }, ["key", "value"]));
-        documentOptions.field = fields;
-        return;
-    }
-    if ([
-        "dependencies",
-        "comments",
-        "notes",
-        "learnings",
-        "files",
-        "tests",
-        "docs",
-        "reminders",
-        "events",
-        "type_options",
-    ].includes(key))
-        return;
-    documentOptions[key.replaceAll(/_([a-z])/gu, (_match, letter) => letter.toUpperCase())] = scalarItemOption(key, value);
-}
-/**
- * Convert a direct item JSON document or `pm get --json` envelope into the
- * create/update option shape. Explicit CLI flags override document values.
- */
-export function itemDocumentToMutationOptions(input, mode, explicitOptions = {}) {
-    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);
-    const documentOptions = {};
-    for (const [key, value] of Object.entries(item)) {
-        appendItemDocumentEntry(documentOptions, key, value, mode);
-    }
-    appendFacetOptions(documentOptions, item, mode === "update");
-    if (linked !== undefined)
-        appendFacetOptions(documentOptions, linked);
-    return {
-        ...documentOptions,
-        ...Object.fromEntries(Object.entries(explicitOptions).filter(([, value]) => value !== undefined)),
-        stdinJson: undefined,
-    };
-}
-/** Validate an already-decoded MCP mutation array through the same strict parser as CLI stdin. */
-export function validateItemMutationRows(value) {
-    return parseItemMutationBatch(JSON.stringify(value));
-}
+!(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]="d6ceb51a-6085-5d65-aebe-31d09ea4d1d6")}catch(e2){}})();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";const MUTATION_ROW_KEYS=["op","id","reason","options"];const REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"];const MUTATION_DOCUMENT_KEYS=["schema_version","mutations"];const MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}";const MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u");const MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu");const flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase());const ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"];const READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]);const UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]);const 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"]);const 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={};const 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 false}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);if(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)return 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);const{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");const 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);if(mutation.options!==void 0){preserveMutationStdinTokenLiterals(mutation.options)}return mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex");const 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);const 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){if(typeof value!=="string")return[];if(value.startsWith("@"))return[value.slice(1)];return[...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:{};const 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;const visited=new Set;const visit=reference=>{if(visiting.has(reference)){throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE)}if(visited.has(reference))return;visiting.add(reference);for(const dependency of graph.get(reference)){if(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");const 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)continue;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);const references=collectMutationReferences(rows,options);assertAcyclicCreateReferences(rows);const resolvedRows=rows.map(row=>{const resolved={...row};const reference=typeof resolved.ref==="string"?resolved.ref:void 0;delete resolved.ref;if(reference!==void 0){resolved.id=references[reference]}else{resolved.id=replaceExactMutationReference(resolved.id,references)}if(isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"]){if(mutationOptions[key]!==void 0){mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references)}}if(Array.isArray(mutationOptions.dep)){mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references))}else if(mutationOptions.dep!==void 0){mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)}resolved.options=mutationOptions}return resolved});const mutations=parseItemMutationBatch(JSON.stringify(resolvedRows));const 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)return 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){if(key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry==="string")){return JSON.stringify(value)}if(typeof value==="number"||typeof value==="boolean"){return String(value)}return value}function appendFacetOptions(target,source,skipPersistedAnnotations=false){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];const serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);if(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){const readOnlyKeys=mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS;if(readOnlyKeys.has(key))return;if(!ITEM_FIELD_KEYS.has(key)){const suggestion=nearestKey(key,[...ITEM_FIELD_KEYS]);if(suggestion!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(serializePairs({key,value:typeof value==="string"?value:JSON.stringify(value)},["key","value"]));documentOptions.field=fields;return}if(["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key))return;documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value)}function itemDocumentToMutationOptions(input,mode,explicitOptions={}){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);const documentOptions={};for(const[key,value]of Object.entries(item)){appendItemDocumentEntry(documentOptions,key,value,mode)}appendFacetOptions(documentOptions,item,mode==="update");if(linked!==void 0)appendFacetOptions(documentOptions,linked);return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,validateItemMutationRows};
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=3f348972-0c8f-52da-abeb-46690df967d8

package/dist/sdk/telemetry-flush.js

@@ -1,14 +1,2 @@
-/**
- * @module sdk/telemetry-flush
- *
- * Owns explicit telemetry queue draining for embedded and detached hosts.
- */
-
-!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]="a108f4d2-80c3-540e-821c-5acdf68eb7fa")}catch(e){}}();
-import { flushTelemetryQueueNow } from "../core/telemetry/runtime.js";
-/** Flush the durable telemetry queue immediately. */
-export async function flushTelemetryQueue() {
-    await flushTelemetryQueueNow();
-}
+!(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]="4534b1c9-de27-5745-88f2-641b00b94714")}catch(e2){}})();import{flushTelemetryQueueNow}from"../core/telemetry/runtime.js";async function flushTelemetryQueue(){await flushTelemetryQueueNow()}export{flushTelemetryQueue};
 //# sourceMappingURL=telemetry-flush.js.map
-//# debugId=a108f4d2-80c3-540e-821c-5acdf68eb7fa