@unbrained/pm-cli 2026.7.4 → 2026.7.5

package/dist/cli/commands/create.js

@@ -4,12 +4,12 @@
  * Implements the pm create 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]="c697cd34-7adc-574e-9180-0b0a387ca5e9")}catch(e){}}();
+!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]="f7516a2a-f728-55b0-99a6-50501443acb4")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic } from "../../core/fs/fs-utils.js";
 import { appendHistoryEntry, createHistoryEntry } from "../../core/history/history.js";
 import { generateItemId, normalizeItemId } from "../../core/item/id.js";
 import { canonicalDocument, normalizeFrontMatter, serializeItemDocument } from "../../core/item/item-format.js";
-import { normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
+import { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
 import { validateSprintOrReleaseValue } from "../../core/item/sprint-release-format.js";
 import { assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNumber, parseTags, } from "../../core/item/parse.js";
 import { resolvePriority } from "../../core/item/priority.js";
@@ -416,6 +416,122 @@ function normalizeCreatePolicyOptionKey(raw, typeName, sourceLabel) {
     }
     return canonical;
 }
+function buildCreateOptionValueLookup(options) {
+    return {
+        scalarValues: {
+            title: options.title,
+            description: options.description,
+            type: options.type,
+            status: options.status,
+            priority: options.priority,
+            tags: options.tags,
+            body: options.body,
+            deadline: options.deadline,
+            estimatedMinutes: options.estimatedMinutes,
+            acceptanceCriteria: options.acceptanceCriteria,
+            definitionOfReady: options.definitionOfReady,
+            order: options.order ?? options.rank,
+            goal: options.goal,
+            objective: options.objective,
+            value: options.value,
+            impact: options.impact,
+            outcome: options.outcome,
+            whyNow: options.whyNow,
+            author: options.author,
+            message: options.message,
+            assignee: options.assignee,
+            parent: options.parent,
+            reviewer: options.reviewer,
+            risk: options.risk,
+            confidence: options.confidence,
+            sprint: options.sprint,
+            release: options.release,
+            blockedBy: options.blockedBy,
+            blockedReason: options.blockedReason,
+            unblockNote: options.unblockNote,
+            reporter: options.reporter,
+            severity: options.severity,
+            environment: options.environment,
+            reproSteps: options.reproSteps,
+            resolution: options.resolution,
+            expectedResult: options.expectedResult,
+            actualResult: options.actualResult,
+            affectedVersion: options.affectedVersion,
+            fixedVersion: options.fixedVersion,
+            component: options.component,
+            regression: options.regression,
+            customerImpact: options.customerImpact,
+        },
+        repeatableValues: {
+            dep: options.dep,
+            comment: options.comment,
+            note: options.note,
+            learning: options.learning,
+            file: options.file,
+            test: options.test,
+            doc: options.doc,
+            reminder: options.reminder,
+            event: options.event,
+            typeOption: options.typeOption,
+            field: options.field,
+        },
+        addTags: options.addTags,
+    };
+}
+function hasCreateOptionValue(lookup, optionKey) {
+    // `--add-tags` mutates the same `tags` field as `--tags`, so it must count
+    // toward the `tags` command_option_policy (both the disabled guard and the
+    // required check) — otherwise `--add-tags` would bypass a rule disabling
+    // tags, or fail to satisfy a rule requiring them even though the created
+    // item ends up tagged.
+    if (optionKey === "tags") {
+        return lookup.scalarValues.tags !== undefined || (Array.isArray(lookup.addTags) && lookup.addTags.length > 0);
+    }
+    if (Object.prototype.hasOwnProperty.call(lookup.scalarValues, optionKey)) {
+        return lookup.scalarValues[optionKey] !== undefined;
+    }
+    /* c8 ignore start -- policy probes only pass canonical CREATE_COMMAND_OPTION_KEYS, all of which exist in scalarValues/repeatableValues, so the in-repeatableValues false arm and trailing return are unreachable. */
+    if (Object.prototype.hasOwnProperty.call(lookup.repeatableValues, optionKey)) {
+        const value = lookup.repeatableValues[optionKey];
+        return Array.isArray(value) && value.length > 0;
+    }
+    return false;
+    /* c8 ignore stop */
+}
+function buildRequiredCreateOptions(typeDefinition, createMode) {
+    const requiredOptions = new Set(["title", "type"]);
+    if (createMode !== "strict") {
+        return requiredOptions;
+    }
+    for (const field of typeDefinition.required_create_fields) {
+        requiredOptions.add(normalizeCreatePolicyOptionKey(field, typeDefinition.name, "required_create_fields"));
+    }
+    for (const field of typeDefinition.required_create_repeatables) {
+        requiredOptions.add(normalizeCreatePolicyOptionKey(field, typeDefinition.name, "required_create_repeatables"));
+    }
+    return requiredOptions;
+}
+function assertNoDisabledCreateOptions(disabledOptions, lookup, clearOptionKeys, typeName) {
+    for (const option of disabledOptions) {
+        if (!hasCreateOptionValue(lookup, option) && !clearOptionKeys.has(option)) {
+            continue;
+        }
+        throw new PmCliError(`Option ${commandOptionFlagLabel("create", option)} is disabled for type "${typeName}" by command_option_policies`, EXIT_CODE.USAGE);
+    }
+}
+function assertNoStrictRequiredOptionClears(requiredOptions, createMode, clearOptionKeys) {
+    if (createMode !== "strict") {
+        return;
+    }
+    const strictRequiredClears = requiredOptions.filter((required) => clearOptionKeys.has(required));
+    if (strictRequiredClears.length === 0) {
+        return;
+    }
+    /* c8 ignore next -- deterministic ordering fallback only matters when required clear list contains locale ties. */
+    const requiredFlags = [...new Set(strictRequiredClears.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
+    /* c8 ignore next -- strict clear conflict envelope is covered by policy integration scenarios. */
+    throw new PmCliError(`Strict create mode requires concrete values for ${requiredFlags.join(", ")}; --unset/--clear-* directives cannot satisfy required options`, EXIT_CODE.USAGE);
+}
 function parseTypeOptions(raw) {
     if (!raw || raw.length === 0) {
         return { values: undefined, explicitEmpty: false };
@@ -483,112 +599,14 @@ function resolveEffectiveCreateMode(createMode, schedulePreset, defaultMode) {
 }
 function requireCreateOptionByType(typeDefinition, options, createMode, clearOptionKeys) {
     const typeName = typeDefinition.name;
-    const scalarValues = {
-        title: options.title,
-        description: options.description,
-        type: options.type,
-        status: options.status,
-        priority: options.priority,
-        tags: options.tags,
-        body: options.body,
-        deadline: options.deadline,
-        estimatedMinutes: options.estimatedMinutes,
-        acceptanceCriteria: options.acceptanceCriteria,
-        definitionOfReady: options.definitionOfReady,
-        order: options.order ?? options.rank,
-        goal: options.goal,
-        objective: options.objective,
-        value: options.value,
-        impact: options.impact,
-        outcome: options.outcome,
-        whyNow: options.whyNow,
-        author: options.author,
-        message: options.message,
-        assignee: options.assignee,
-        parent: options.parent,
-        reviewer: options.reviewer,
-        risk: options.risk,
-        confidence: options.confidence,
-        sprint: options.sprint,
-        release: options.release,
-        blockedBy: options.blockedBy,
-        blockedReason: options.blockedReason,
-        unblockNote: options.unblockNote,
-        reporter: options.reporter,
-        severity: options.severity,
-        environment: options.environment,
-        reproSteps: options.reproSteps,
-        resolution: options.resolution,
-        expectedResult: options.expectedResult,
-        actualResult: options.actualResult,
-        affectedVersion: options.affectedVersion,
-        fixedVersion: options.fixedVersion,
-        component: options.component,
-        regression: options.regression,
-        customerImpact: options.customerImpact,
-    };
-    const repeatableValues = {
-        dep: options.dep,
-        comment: options.comment,
-        note: options.note,
-        learning: options.learning,
-        file: options.file,
-        test: options.test,
-        doc: options.doc,
-        reminder: options.reminder,
-        event: options.event,
-        typeOption: options.typeOption,
-        field: options.field,
-    };
-    const hasOptionValue = (optionKey) => {
-        // `--add-tags` mutates the same `tags` field as `--tags`, so it must count
-        // toward the `tags` command_option_policy (both the disabled guard and the
-        // required check) — otherwise `--add-tags` would bypass a rule disabling
-        // tags, or fail to satisfy a rule requiring them even though the created
-        // item ends up tagged.
-        if (optionKey === "tags") {
-            return scalarValues.tags !== undefined || (Array.isArray(options.addTags) && options.addTags.length > 0);
-        }
-        if (optionKey in scalarValues) {
-            return scalarValues[optionKey] !== undefined;
-        }
-        /* c8 ignore start -- policy probes only pass canonical CREATE_COMMAND_OPTION_KEYS, all of which exist in scalarValues/repeatableValues, so the in-repeatableValues false arm and trailing return are unreachable. */
-        if (optionKey in repeatableValues) {
-            const value = repeatableValues[optionKey];
-            return Array.isArray(value) && value.length > 0;
-        }
-        return false;
-        /* c8 ignore stop */
-    };
-    /* c8 ignore next -- policy probes only pass normalized option keys in command-level tests. */
-    const hasOptionMutation = (optionKey) => hasOptionValue(optionKey) || clearOptionKeys.has(optionKey);
-    const baseRequiredOptions = new Set(["title", "type"]);
-    if (createMode === "strict") {
-        for (const field of typeDefinition.required_create_fields) {
-            baseRequiredOptions.add(normalizeCreatePolicyOptionKey(field, typeName, "required_create_fields"));
-        }
-        for (const field of typeDefinition.required_create_repeatables) {
-            baseRequiredOptions.add(normalizeCreatePolicyOptionKey(field, typeName, "required_create_repeatables"));
-        }
-    }
+    const optionLookup = buildCreateOptionValueLookup(options);
+    const baseRequiredOptions = buildRequiredCreateOptions(typeDefinition, createMode);
     const policyState = resolveCommandOptionPolicyState(typeDefinition, "create", baseRequiredOptions);
     if (policyState.errors.length > 0) {
         throw new PmCliError(policyState.errors.join("; "), EXIT_CODE.CONFLICT);
     }
-    for (const option of policyState.disabled) {
-        if (hasOptionMutation(option)) {
-            throw new PmCliError(`Option ${commandOptionFlagLabel("create", option)} is disabled for type "${typeName}" by command_option_policies`, EXIT_CODE.USAGE);
-        }
-    }
-    if (createMode === "strict") {
-        const strictRequiredClears = policyState.required.filter((required) => clearOptionKeys.has(required));
-        if (strictRequiredClears.length > 0) {
-            /* c8 ignore next -- deterministic ordering fallback only matters when required clear list contains locale ties. */
-            const requiredFlags = [...new Set(strictRequiredClears.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
-            /* c8 ignore next -- strict clear conflict envelope is covered by policy integration scenarios. */
-            throw new PmCliError(`Strict create mode requires concrete values for ${requiredFlags.join(", ")}; --unset/--clear-* directives cannot satisfy required options`, EXIT_CODE.USAGE);
-        }
-    }
+    assertNoDisabledCreateOptions(policyState.disabled, optionLookup, clearOptionKeys, typeName);
+    assertNoStrictRequiredOptionClears(policyState.required, createMode, clearOptionKeys);
     // A configured per-type default_status satisfies a required `status` policy:
     // when --status is omitted, runCreate resolves to that default (or degrades to
     // the workflow open status), so blocking the agent for a "missing --status"
@@ -599,7 +617,7 @@ function requireCreateOptionByType(typeDefinition, options, createMode, clearOpt
         if (optionKey === "status" && typeDefinition.default_status !== undefined) {
             return true;
         }
-        return hasOptionValue(optionKey);
+        return hasCreateOptionValue(optionLookup, optionKey);
     };
     const missingRequiredOptions = policyState.required.filter((required) => !satisfiesRequiredOption(required));
     return [...new Set(missingRequiredOptions.map((required) => commandOptionFlagLabel("create", required)))].sort((left, right) => left.localeCompare(right));
@@ -864,8 +882,9 @@ async function inheritFocusedParent(parent, resolvedOptions, unsetKeys, pmRoot)
  * value plus any never-blocking missing-parent warnings the configured
  * `parent_reference` policy produces when the target does not resolve.
  */
-async function validateCreateParentReference(pmRoot, settings, typeRegistry, parent, policy) {
+async function validateCreateParentReference(pmRoot, settings, typeRegistry, itemId, parent, policy) {
     const normalized = normalizeParentReferenceValue(parent);
+    assertParentReferenceIsNotSelf(itemId, normalized, settings.id_prefix);
     const parentLocated = await locateItem(pmRoot, normalized, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
     if (parentLocated) {
         return { parent: normalized, warnings: [] };
@@ -877,9 +896,26 @@ async function resolveCreateParentWithWarnings(params) {
     if (params.parent === undefined) {
         return { parent: undefined, warnings: [] };
     }
-    const parentValidation = await validateCreateParentReference(params.pmRoot, params.settings, params.typeRegistry, params.parent, params.policy);
+    const parentValidation = await validateCreateParentReference(params.pmRoot, params.settings, params.typeRegistry, params.itemId, params.parent, params.policy);
     return parentValidation;
 }
+async function resolveCreateItemId(params) {
+    if (params.explicitId === undefined) {
+        return generateItemId(params.pmRoot, params.settings.id_prefix);
+    }
+    if (typeof params.explicitId !== "string") {
+        throw new PmCliError("--id must be a string", EXIT_CODE.USAGE);
+    }
+    const trimmedId = params.explicitId.trim();
+    if (trimmedId.length === 0 || isPlaceholderReferenceToken(trimmedId)) {
+        throw new PmCliError("--id must not be empty or use a placeholder token", EXIT_CODE.USAGE);
+    }
+    const normalizedId = normalizeItemId(trimmedId, params.settings.id_prefix);
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(normalizedId)) {
+        throw new PmCliError("--id must contain only letters, numbers, and dashes after normalization", EXIT_CODE.USAGE);
+    }
+    return normalizedId;
+}
 /**
  * Resolve a sprint or release field: `undefined` when cleared/absent, otherwise
  * the format-validated value plus any never-blocking format warnings from the
@@ -1268,9 +1304,13 @@ async function writeCreatedItem(params) {
     const { pmRoot, type, id, settings, typeRegistry, author, extensionFieldNames, afterDocument, beforeDocument, historyMessage, changedFields, nowValue } = params;
     const itemPath = getItemPath(pmRoot, type, id, settings.item_format, typeRegistry.type_to_folder);
     const historyPath = getHistoryPath(pmRoot, id);
-    const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock);
+    const lockRelease = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author, false, settings.governance.force_required_for_stale_lock, settings.locks.wait_ms);
     let hookWarnings = [];
     try {
+        const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+        if (existing) {
+            throw new PmCliError(`Item "${id}" already exists`, EXIT_CODE.CONFLICT);
+        }
         await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: settings.item_format, schema: settings.schema, extensionFieldNames }));
         try {
             const entry = createHistoryEntry({ nowIso: nowValue, author, op: "create", before: beforeDocument, after: afterDocument, message: historyMessage });
@@ -1373,7 +1413,11 @@ export async function runCreate(options, global) {
         createMode,
     });
     assertNoInvalidTypeOptions(validatedTypeOptions.errors, type, typeDefinition, statusRegistry);
-    const id = await generateItemId(pmRoot, settings.id_prefix);
+    const id = await resolveCreateItemId({
+        pmRoot,
+        settings,
+        explicitId: resolvedOptions.id,
+    });
     let status = resolvedOptions.status !== undefined
         ? parseStatusValue(resolvedOptions.status, statusRegistry)
         : resolveCreateDefaultStatus(typeDefinition, statusRegistry);
@@ -1410,6 +1454,7 @@ export async function runCreate(options, global) {
     const sprintReleasePolicy = settings.validation.sprint_release_format;
     const validationWarnings = collectCreateScheduleWarnings(type, id, deadline, reminders.values, events.values);
     const parentValidation = await resolveCreateParentWithWarnings({
+        itemId: id,
         parent,
         pmRoot,
         settings,
@@ -1587,6 +1632,7 @@ export const _testOnlyCreateCommand = {
     createExampleTokensForFlag,
     filterNonMissingTypeOptionErrors,
     hasTemplatesShowHandler,
+    hasCreateOptionValue,
     loadCreateTemplateOptionsFromRuntime,
     looksLikeStructuredEntry,
     mergeCreateOptionsWithTemplate,
@@ -1600,4 +1646,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=c697cd34-7adc-574e-9180-0b0a387ca5e9
+//# debugId=f7516a2a-f728-55b0-99a6-50501443acb4