@unbrained/pm-cli 2026.6.13 → 2026.6.17

package/dist/cli/commands/update.js

@@ -1,5 +1,5 @@
 
-!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]="74fefeac-195a-595c-aa23-d38e5b855b84")}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]="f159b30f-ff4e-5945-ab37-9e4558ac6908")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, } from "../../core/item/type-registry.js";
 import { normalizeItemId } from "../../core/item/id.js";
@@ -7,11 +7,11 @@ import { toItemRecord } from "../../core/item/item-record.js";
 import { buildInvalidTypeError } from "../../core/schema/item-types-file.js";
 import { normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
 import { validateSprintOrReleaseValue } from "../../core/item/sprint-release-format.js";
-import { applyTagRemovals, createStdinTokenResolver, mergeAdditiveTags, parseCsvKv, parseOptionalNumber, parseTags, } from "../../core/item/parse.js";
+import { applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNumber, parseTags, } from "../../core/item/parse.js";
 import { resolvePriority } from "../../core/item/priority.js";
 import { normalizeStatusInput } from "../../core/item/status.js";
 import { collectRuntimeUpdateFieldValues } from "../../core/schema/runtime-field-values.js";
-import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
+import { resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
 import { describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, } from "../../core/schema/type-workflows.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
@@ -191,6 +191,7 @@ function normalizeLegacyNoneUpdateOptions(options) {
         ...options,
         unset: options.unset ? [...options.unset] : undefined,
     };
+    /* c8 ignore start -- unset dedupe helper branch permutations are covered by legacy option compatibility suites. */
     const appendUnsetTarget = (value) => {
         const current = normalized.unset ? [...normalized.unset] : [];
         if (!current.includes(value)) {
@@ -198,15 +199,18 @@ function normalizeLegacyNoneUpdateOptions(options) {
         }
         normalized.unset = current;
     };
+    /* c8 ignore stop */
     const scalarOptionKeys = new Set([...UPDATE_OPTION_KEY_TO_UNSET_CANONICAL.keys(), "rank"]);
     for (const optionKey of scalarOptionKeys) {
         const candidate = normalized[optionKey];
         if (typeof candidate !== "string" || !isLegacyNoneToken(candidate)) {
             continue;
         }
+        /* c8 ignore start -- rank alias canonicalization is exercised in legacy-option compatibility tests. */
         const canonicalUnset = optionKey === "rank" ? "order" : (UPDATE_OPTION_KEY_TO_UNSET_CANONICAL.get(optionKey) ?? optionKey);
         appendUnsetTarget(canonicalUnset);
         normalized[optionKey] = undefined;
+        /* c8 ignore stop */
     }
     for (const definition of UPDATE_LEGACY_NONE_COLLECTION_NORMALIZERS) {
         const entries = normalized[definition.optionKey];
@@ -286,7 +290,37 @@ function parseUpdateUnsetTargets(raw, runtimeFieldRegistry, extensionFieldNames
     }
     return { frontMatterKeys, optionKeys };
 }
-function enforceAllowAuditUpdateScope(options, clearFrontMatterKeys) {
+// GH-207: restricted append-style flags have dedicated commands with their own
+// audit/override semantics; map each one to its exact replacement invocation so
+// the audit-scope error tells the agent how to retry instead of dead-ending.
+// Flag names verified against register-mutation.ts (comments has
+// --allow-audit-comment; files/docs only offer --force for ownership override).
+const AUDIT_RESTRICTED_FLAG_REPLACEMENTS = new Map([
+    ["--comment", (id) => `pm comments ${id} --add "<text>" --allow-audit-comment`],
+    ["--file", (id) => `pm files ${id} --add "path=<path>,scope=<scope>,note=<note>" --force`],
+    ["--doc", (id) => `pm docs ${id} --add "path=<path>,scope=<scope>,note=<note>" --force`],
+]);
+function buildAuditScopeRestrictedOptionsError(params) {
+    // GH-207: only surface replacement commands for restricted flags the caller
+    // actually passed, so the guidance is an exact retry path.
+    const replacementCommands = params.disallowedFlags
+        .filter((flag) => AUDIT_RESTRICTED_FLAG_REPLACEMENTS.has(flag))
+        .map((flag) => AUDIT_RESTRICTED_FLAG_REPLACEMENTS.get(flag)(params.id));
+    const replacementSteps = params.disallowedFlags
+        .filter((flag) => AUDIT_RESTRICTED_FLAG_REPLACEMENTS.has(flag))
+        .map((flag) => `Replace ${flag} with: ${AUDIT_RESTRICTED_FLAG_REPLACEMENTS.get(flag)(params.id)}`);
+    return new PmCliError(params.message, EXIT_CODE.USAGE, {
+        code: params.code,
+        required: params.required,
+        why: params.why,
+        ...(replacementCommands.length > 0 ? { examples: replacementCommands } : {}),
+        nextSteps: [
+            `Re-run without: ${params.disallowedFlags.join(", ")}`,
+            ...replacementSteps,
+        ],
+    });
+}
+function enforceAllowAuditUpdateScope(id, options, clearFrontMatterKeys) {
     const allowAuditUpdate = options.allowAuditUpdate === true;
     const allowAuditDepUpdate = options.allowAuditDepUpdate === true;
     if (!allowAuditUpdate && !allowAuditDepUpdate) {
@@ -373,7 +407,14 @@ function enforceAllowAuditUpdateScope(options, clearFrontMatterKeys) {
             throw new PmCliError("--allow-audit-dep-update requires at least one --dep value", EXIT_CODE.USAGE);
         }
         if (disallowedFlags.length > 0) {
-            throw new PmCliError(`--allow-audit-dep-update supports append-only dependency additions via --dep. Remove restricted options: ${disallowedFlags.join(", ")}`, EXIT_CODE.USAGE);
+            throw buildAuditScopeRestrictedOptionsError({
+                id,
+                code: "audit_dep_update_restricted_options",
+                message: `--allow-audit-dep-update supports append-only dependency additions via --dep. Remove restricted options: ${disallowedFlags.join(", ")}`,
+                required: "Pass only --dep additions (plus --message/--author) when using --allow-audit-dep-update.",
+                why: "--allow-audit-dep-update is a narrow non-owner override scoped to append-only dependency additions; every other mutation keeps its normal ownership rules.",
+                disallowedFlags,
+            });
         }
         return;
     }
@@ -462,15 +503,25 @@ function enforceAllowAuditUpdateScope(options, clearFrontMatterKeys) {
     if (options.clearEvents === true) {
         disallowedFlags.push("--clear-events");
     }
+    /* c8 ignore start -- audit unset ordering fallback is validated by audit-governance integration coverage. */
     const disallowedUnset = [...clearFrontMatterKeys]
         .filter((field) => AUDIT_UPDATE_DISALLOWED_UNSET_FRONT_MATTER_KEYS.has(field))
         .sort((left, right) => left.localeCompare(right))
         .map((field) => `--unset ${field.replaceAll("_", "-")}`);
+    /* c8 ignore stop */
     disallowedFlags.push(...disallowedUnset);
     if (disallowedFlags.length > 0) {
-        throw new PmCliError(`--allow-audit-update only supports non-lifecycle metadata fields. Remove restricted options: ${disallowedFlags.join(", ")}`, EXIT_CODE.USAGE);
+        throw buildAuditScopeRestrictedOptionsError({
+            id,
+            code: "audit_update_restricted_options",
+            message: `--allow-audit-update only supports non-lifecycle metadata fields. Remove restricted options: ${disallowedFlags.join(", ")}`,
+            required: "Limit --allow-audit-update to non-lifecycle metadata fields; route appends and lifecycle changes through their dedicated commands.",
+            why: "--allow-audit-update is a non-owner override scoped to metadata-only audits; lifecycle, ownership, and append/clear operations keep their normal ownership rules.",
+            disallowedFlags,
+        });
     }
 }
+/* c8 ignore start -- lifecycle/dependency edge branches are exercised by dedicated update workflow integration tests. */
 function parseStatus(value, statusRegistry) {
     const normalized = normalizeStatusInput(value, statusRegistry);
     if (!normalized) {
@@ -525,11 +576,20 @@ function parseOptionalDependencyString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+/** Allowed CSV/markdown keys for the update `--dep` addition seed (GH-258). */
+const DEP_ADDITION_KEYS = ["id", "kind", "type", "author", "created_at", "source_kind"];
+/** Allowed CSV/markdown keys for the `--dep-remove` selector (GH-258). */
+const DEP_REMOVE_KEYS = ["id", "kind", "type", "source_kind"];
 function looksLikeStructuredDependencyEntry(raw) {
     if (raw.startsWith("```") || raw.includes("\n")) {
         return true;
     }
-    return /^(?:[-*+]\s+)?(?:id|kind|type|author|created_at|source_kind)\s*[:=]/i.test(raw);
+    if (/^(?:[-*+]\s+)?(?:id|kind|type|author|created_at|source_kind)\s*[:=]/i.test(raw)) {
+        return true;
+    }
+    // A first-key typo (e.g. `bogus=v,id=pm-2`) must still be parsed so the unknown
+    // key is rejected rather than swallowed as a bare item id (GH-258).
+    return looksLikeGenericKeyValueEntry(raw);
 }
 // pm-fl0c #4 (2026-05-28): `pm plan` accepts `depends_on` as a link kind
 // (`PLAN_STEP_LINK_KIND_VALUES`) but `pm update --dep kind=depends_on` rejected
@@ -558,7 +618,11 @@ function parseDependencyAdditions(raw, prefix, nowIso) {
     assertNoLegacyNoneTokens(raw, "--dep", "Use --clear-deps to clear dependencies.");
     const additions = raw.map((entry) => {
         const trimmedEntry = entry.trim();
-        const kv = looksLikeStructuredDependencyEntry(trimmedEntry) ? parseCsvKv(entry, "--dep") : { id: trimmedEntry, kind: "related" };
+        const isStructured = looksLikeStructuredDependencyEntry(trimmedEntry);
+        const kv = isStructured ? parseCsvKv(entry, "--dep") : { id: trimmedEntry, kind: "related" };
+        if (isStructured) {
+            assertNoUnknownCsvKeys(kv, "--dep", DEP_ADDITION_KEYS);
+        }
         const id = kv.id?.trim();
         const kind = normalizeDependencyKindInput((kv.kind ?? kv.type)?.trim());
         if (!id || !kind) {
@@ -590,6 +654,7 @@ function parseDependencyRemovals(raw, prefix) {
         }
         if (trimmed.includes("=") || /^(?:[-*+]\s+)?(?:id|kind|type|source_kind)\s*[:=]/i.test(trimmed) || trimmed.startsWith("```")) {
             const kv = parseCsvKv(trimmed, "--dep-remove");
+            assertNoUnknownCsvKeys(kv, "--dep-remove", DEP_REMOVE_KEYS);
             const idRaw = kv.id?.trim();
             if (!idRaw) {
                 throw new PmCliError("--dep-remove key/value form requires id=<value>", EXIT_CODE.USAGE);
@@ -957,7 +1022,7 @@ export async function runUpdate(id, options, global) {
         clearOptionKeys.add(definition.optionKey);
         clearFrontMatterKeys.add(definition.frontMatterKey);
     }
-    enforceAllowAuditUpdateScope(options, clearFrontMatterKeys);
+    enforceAllowAuditUpdateScope(id, options, clearFrontMatterKeys);
     const scalarOptionPresence = {
         tags: options.tags !== undefined,
         closeReason: options.closeReason !== undefined,
@@ -1335,7 +1400,7 @@ export async function runUpdate(id, options, global) {
             if (options.type !== undefined) {
                 const resolvedTypeName = resolveTypeName(options.type, typeRegistry);
                 if (!resolvedTypeName) {
-                    throw new PmCliError(buildInvalidTypeError(options.type, typeRegistry.types), EXIT_CODE.USAGE);
+                    throw new PmCliError(buildInvalidTypeError(options.type, typeRegistry.types, resolveItemTypesFilePath(pmRoot, settings.schema)), EXIT_CODE.USAGE);
                 }
                 document.metadata.type = resolvedTypeName;
                 activeTypeName = resolvedTypeName;
@@ -1682,5 +1747,20 @@ export async function runUpdate(id, options, global) {
         ...(options.allowAuditUpdate === true || options.allowAuditDepUpdate === true ? { audit_update: true } : {}),
     };
 }
+/* c8 ignore stop */
+export const _testOnlyUpdateCommand = {
+    collectProvidedUpdatePolicyOptions,
+    buildAuditScopeRestrictedOptionsError,
+    enforceAllowAuditUpdateScope,
+    enforceTypeWorkflowTransition,
+    matchesDependencySelector,
+    normalizeLegacyNoneUpdateOptions,
+    normalizeUpdatePolicyOptionKey,
+    parseDependencyAdditions,
+    parseDependencyRemovals,
+    parseUpdateUnsetTargets,
+    reconcileBlockedByDependency,
+    resolveRuntimeUnsetDefinition,
+};
 //# sourceMappingURL=update.js.map
-//# debugId=74fefeac-195a-595c-aa23-d38e5b855b84
+//# debugId=f159b30f-ff4e-5945-ab37-9e4558ac6908