@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/dist/cli/error-guidance.js

@@ -1,3 +1,4 @@
+import { renderPmCommand } from "./argv-utils.js";
 function errorType(code) {
     return `urn:pm-cli:error:${code}`;
 }
@@ -13,6 +14,60 @@ function renderList(title, entries) {
     }
     return [title, ...entries.map((entry) => `  - ${entry}`)];
 }
+function normalizeRecoveryPayload(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const normalized = {};
+    if (typeof payload.attempted_command === "string" && payload.attempted_command.trim().length > 0) {
+        normalized.attempted_command = payload.attempted_command.trim();
+    }
+    if (Array.isArray(payload.normalized_args)) {
+        const args = payload.normalized_args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (args.length > 0) {
+            normalized.normalized_args = args;
+        }
+    }
+    if (Array.isArray(payload.provided_fields)) {
+        const fields = payload.provided_fields.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (fields.length > 0) {
+            normalized.provided_fields = fields;
+        }
+    }
+    if (Array.isArray(payload.missing)) {
+        const missing = payload.missing.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+        if (missing.length > 0) {
+            normalized.missing = missing;
+        }
+    }
+    if (typeof payload.suggested_retry === "string" && payload.suggested_retry.trim().length > 0) {
+        normalized.suggested_retry = payload.suggested_retry.trim();
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+function renderRecoveryBundle(recovery) {
+    const normalized = normalizeRecoveryPayload(recovery);
+    if (!normalized) {
+        return [];
+    }
+    const lines = ["Recovery bundle:"];
+    if (normalized.attempted_command) {
+        lines.push(`  attempted_command: ${normalized.attempted_command}`);
+    }
+    if (normalized.normalized_args && normalized.normalized_args.length > 0) {
+        lines.push(`  normalized_args: ${normalized.normalized_args.join(" ")}`);
+    }
+    if (normalized.provided_fields && normalized.provided_fields.length > 0) {
+        lines.push(`  provided_fields: ${normalized.provided_fields.join(", ")}`);
+    }
+    if (normalized.missing && normalized.missing.length > 0) {
+        lines.push(`  missing: ${normalized.missing.join(", ")}`);
+    }
+    if (normalized.suggested_retry) {
+        lines.push(`  suggested_retry: ${normalized.suggested_retry}`);
+    }
+    return lines;
+}
 export function renderGuidanceMessage(message) {
     const lines = [
         `Error: ${message.title}`,
@@ -35,6 +90,11 @@ export function renderGuidanceMessage(message) {
         lines.push("");
         lines.push(...renderList("Next steps:", message.nextSteps));
     }
+    const recoveryLines = renderRecoveryBundle(message.recovery);
+    if (recoveryLines.length > 0) {
+        lines.push("");
+        lines.push(...recoveryLines);
+    }
     return lines.join("\n");
 }
 function guidanceToJsonEnvelope(message, exitCode) {
@@ -55,6 +115,9 @@ function guidanceToJsonEnvelope(message, exitCode) {
     if (message.nextSteps && message.nextSteps.length > 0) {
         payload.next_steps = message.nextSteps;
     }
+    if (message.recovery) {
+        payload.recovery = message.recovery;
+    }
     return payload;
 }
 function guidanceToClassification(message) {
@@ -74,6 +137,9 @@ function guidanceToClassification(message) {
     if (message.nextSteps && message.nextSteps.length > 0) {
         payload.next_steps = message.nextSteps;
     }
+    if (message.recovery) {
+        payload.recovery = message.recovery;
+    }
     return payload;
 }
 function normalizeMessage(message) {
@@ -106,6 +172,7 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
     const examples = normalizeContextList(context.examples) ?? guidance.examples;
     const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;
     const fallbackTitle = guidance.code === "command_failed" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;
+    const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;
     return {
         ...guidance,
         code,
@@ -116,6 +183,7 @@ function applyPmCliErrorContext(guidance, rawMessage, context) {
         why: typeof context.why === "string" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,
         examples,
         nextSteps,
+        recovery,
     };
 }
 function buildPmCliErrorGuidance(rawMessage, context) {
@@ -267,12 +335,65 @@ function commandExampleForRequiredOption(commandName, optionFlag, allowedTypes)
     }
     return [`pm ${commandName ?? "<command>"} --help`];
 }
+function normalizeRequiredOptionLabel(rawValue) {
+    const normalized = rawValue.trim();
+    const firstLongFlag = normalized.match(/--[A-Za-z0-9][A-Za-z0-9_-]*/)?.[0];
+    return firstLongFlag ?? normalized;
+}
+function renderPmCommandFromArgs(argv) {
+    if (!Array.isArray(argv) || argv.length === 0) {
+        return undefined;
+    }
+    return renderPmCommand(argv);
+}
+function normalizeOptionFlags(values) {
+    if (!Array.isArray(values)) {
+        return undefined;
+    }
+    const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);
+    return normalized.length > 0 ? normalized : undefined;
+}
+function buildCommanderRecoveryPayload(context, overrides = {}) {
+    const providedFields = normalizeOptionFlags(context?.providedOptionFlags);
+    const normalizedArgs = Array.isArray(context?.normalizedInvocationArgs) && context?.normalizedInvocationArgs.length > 0
+        ? context.normalizedInvocationArgs
+        : undefined;
+    const attemptedCommand = typeof context?.attemptedCommand === "string" ? context.attemptedCommand : renderPmCommandFromArgs(normalizedArgs);
+    const retryCommand = typeof context?.suggestedRetryCommand === "string" ? context.suggestedRetryCommand : undefined;
+    return normalizeRecoveryPayload({
+        attempted_command: attemptedCommand,
+        normalized_args: normalizedArgs,
+        provided_fields: providedFields,
+        suggested_retry: retryCommand,
+        ...overrides,
+    });
+}
+function appendIfMissing(entries, value) {
+    if (!value || entries.includes(value)) {
+        return entries;
+    }
+    return [...entries, value];
+}
 function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context) {
     const message = normalizeMessage(rawMessage);
     const requiredOption = message.match(/required option '([^']+)' not specified/);
     if (requiredOption) {
-        const optionFlag = requiredOption[1];
+        const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);
         const isType = optionFlag.startsWith("--type");
+        const retryCommand = context?.suggestedRetryCommand;
+        const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);
+        const missing = [optionFlag];
+        const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);
+        const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;
+        const nextStepsBase = isType
+            ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`]
+            : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`];
+        const nextStepsWithRetry = retryCommand
+            ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`)
+            : nextStepsBase;
+        const nextSteps = providedFlags && providedFlags.length > 0
+            ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(", ")}`)
+            : nextStepsWithRetry;
         return makeGuidanceMessage({
             code: "missing_required_option",
             title: `Missing required option ${optionFlag}`,
@@ -281,10 +402,9 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             why: isType
                 ? "--type selects item contract and policy routing, including required/disabled option rules."
                 : "Required flags define mandatory command intent and prevent ambiguous execution.",
-            examples: commandExampleForRequiredOption(commandName, optionFlag, allowedTypes),
-            nextSteps: isType
-                ? [`Allowed type values: ${allowedTypes}`, `Run "pm ${commandName ?? "create"} --help --type <value>" for type-aware policy details.`]
-                : [`Run "pm ${commandName ?? "<command>"} --help" for required option guidance.`],
+            examples: examplesWithRetry,
+            nextSteps,
+            recovery: buildCommanderRecoveryPayload(context, { missing }),
         });
     }
     const missingArgument = message.match(/missing required argument '([^']+)'/);
@@ -297,11 +417,14 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             required: `Provide ${argumentName} in the expected command position.`,
             why: "Positional arguments identify the target entity or action context for the command.",
             examples: [`pm ${commandName ?? "<command>"} --help`],
+            recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] }),
         });
     }
     const unknownOption = message.match(/unknown option '([^']+)'/);
     if (unknownOption) {
         const optionName = unknownOption[1];
+        const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
+        const retryCommand = context?.suggestedRetryCommand;
         if (commandName === "update" && (optionName === "--file" || optionName === "--doc")) {
             return makeGuidanceMessage({
                 code: "unsupported_update_option",
@@ -314,15 +437,31 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
                     'pm docs pm-a1b2 --add "path=README.md,scope=project,note=user-facing contract"',
                 ],
                 nextSteps: ['Run "pm files --help" and "pm docs --help" for add/remove payload formats.'],
+                recovery: buildCommanderRecoveryPayload(context, {
+                    missing: suggestions,
+                }),
             });
         }
+        const nextSteps = [
+            "Run command help to confirm the exact option contracts for this command path.",
+            ...(suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(", ")}`] : []),
+            ...(retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []),
+        ];
+        const examples = [
+            ...(retryCommand ? [retryCommand] : []),
+            `pm ${commandName ?? "<command>"} --help`,
+        ];
         return makeGuidanceMessage({
             code: "unknown_option",
             title: `Unknown option ${optionName}`,
             happened: `Commander does not recognize option ${optionName} for this command path.`,
             required: "Use supported options only, or move option to the correct subcommand.",
             why: "Option contracts are command-specific and intentionally validated.",
-            examples: [`pm ${commandName ?? "<command>"} --help`],
+            examples,
+            nextSteps,
+            recovery: buildCommanderRecoveryPayload(context, {
+                missing: suggestions,
+            }),
         });
     }
     const unknownCommand = message.match(/unknown command '([^']+)'/);
@@ -338,6 +477,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
             why: "Command registry includes core commands plus active extension command handlers.",
             examples: runtimeExamples ?? ["pm --help"],
             nextSteps: runtimeNextSteps ?? ["Verify spelling and active extensions, then rerun."],
+            recovery: buildCommanderRecoveryPayload(context),
         });
     }
     return makeGuidanceMessage({
@@ -347,6 +487,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         required: "Use the command with valid arguments and options.",
         why: "Commander validates CLI contracts before execution.",
         examples: ["pm --help", `pm ${commandName ?? "<command>"} --help`],
+        recovery: buildCommanderRecoveryPayload(context),
     });
 }
 export function formatPmCliErrorForDisplay(rawMessage, context) {

package/dist/cli/error-guidance.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-guidance.js","sourceRoot":"/","sources":["cli/error-guidance.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PmCliErrorContext } from \"../core/shared/errors.js\";\n\ninterface GuidanceMessage {\n  code: string;\n  type: string;\n  title: string;\n  happened: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  nextSteps?: string[];\n}\n\nexport interface JsonErrorEnvelope {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  exit_code: number;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n}\n\nexport interface ErrorClassification {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n}\n\nexport interface CommanderGuidanceContext {\n  unknownCommandExamples?: string[];\n  unknownCommandNextSteps?: string[];\n}\n\nfunction errorType(code: string): string {\n  return `urn:pm-cli:error:${code}`;\n}\n\nfunction makeGuidanceMessage(params: Omit<GuidanceMessage, \"type\">): GuidanceMessage {\n  return {\n    ...params,\n    type: errorType(params.code),\n  };\n}\n\nfunction renderList(title: string, entries: string[]): string[] {\n  if (entries.length === 0) {\n    return [];\n  }\n  return [title, ...entries.map((entry) => `  - ${entry}`)];\n}\n\nexport function renderGuidanceMessage(message: GuidanceMessage): string {\n  const lines: string[] = [\n    `Error: ${message.title}`,\n    \"\",\n    \"What happened:\",\n    `  ${message.happened}`,\n    \"\",\n    \"What is required:\",\n    `  ${message.required}`,\n  ];\n  if (message.why) {\n    lines.push(\"\", \"Why:\");\n    lines.push(`  ${message.why}`);\n  }\n  if (message.examples && message.examples.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Examples:\", message.examples));\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Next steps:\", message.nextSteps));\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: number): JsonErrorEnvelope {\n  const payload: JsonErrorEnvelope = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n    exit_code: exitCode,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  return payload;\n}\n\nfunction guidanceToClassification(message: GuidanceMessage): ErrorClassification {\n  const payload: ErrorClassification = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  return payload;\n}\n\nfunction normalizeMessage(message: string): string {\n  return message.replace(/\\(outputHelp\\)/g, \"\").trim();\n}\n\nfunction normalizeContextList(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildFallbackTitleFromMessage(message: string): string | undefined {\n  const firstLine = message.split(/\\r?\\n/)[0]?.trim() ?? \"\";\n  if (firstLine.length === 0) {\n    return undefined;\n  }\n  if (firstLine.length <= 120) {\n    return firstLine;\n  }\n  return `${firstLine.slice(0, 117)}...`;\n}\n\nfunction applyPmCliErrorContext(\n  guidance: GuidanceMessage,\n  rawMessage: string,\n  context: PmCliErrorContext | undefined,\n): GuidanceMessage {\n  if (!context) {\n    return guidance;\n  }\n  const normalizedRawMessage = normalizeMessage(rawMessage);\n  const code = typeof context.code === \"string\" && context.code.trim().length > 0 ? context.code.trim() : guidance.code;\n  const type = typeof context.type === \"string\" && context.type.trim().length > 0 ? context.type.trim() : errorType(code);\n  const examples = normalizeContextList(context.examples) ?? guidance.examples;\n  const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;\n  const fallbackTitle = guidance.code === \"command_failed\" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;\n  return {\n    ...guidance,\n    code,\n    type,\n    title: fallbackTitle ?? guidance.title,\n    happened: normalizedRawMessage.length > 0 ? normalizedRawMessage : guidance.happened,\n    required: typeof context.required === \"string\" && context.required.trim().length > 0 ? context.required.trim() : guidance.required,\n    why: typeof context.why === \"string\" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,\n    examples,\n    nextSteps,\n  };\n}\n\nfunction buildPmCliErrorGuidance(rawMessage: string, context?: PmCliErrorContext): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\\. Run pm init first\\.$/);\n  if (trackerNotInitialized) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"tracker_not_initialized\",\n        title: \"Tracker is not initialized\",\n        happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,\n        required: \"Initialize tracker storage before running this command.\",\n        why: \"Most commands require settings and tracker directories created by pm init.\",\n        examples: [\"pm init\", \"pm init acme\"],\n        nextSteps: ['Run \"pm init\", then rerun your original command.'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const itemNotFound = message.match(/^Item ([^ ]+) not found$/);\n  if (itemNotFound) {\n    const badId = itemNotFound[1];\n    const isPlaceholder = /^(undefined|null|<.*>|\\[.*\\]|{.*}|)$/.test(badId);\n    const happened = isPlaceholder\n      ? `The item ID \"${badId}\" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.`\n      : `No item with id \"${badId}\" exists in the active tracker scope.`;\n    const nextSteps = isPlaceholder\n      ? [\n          \"Check that the variable holding the item ID is defined before passing it to pm.\",\n          'Use \"pm list-open --limit 20\" to find valid IDs.',\n        ]\n      : [\"Confirm the active --path/PM_PATH scope, then retry with a valid id.\"];\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"item_not_found\",\n        title: \"Item ID not found\",\n        happened,\n        required: \"Use an existing item ID from current tracker data.\",\n        why: \"Mutation and read commands operate only on known IDs.\",\n        examples: ['pm list-open --limit 20', 'pm search \"<keyword>\" --limit 10'],\n        nextSteps,\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is assigned to\") && message.includes(\"Use --force to override\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"ownership_conflict\",\n        title: \"Ownership conflict\",\n        happened: message,\n        required:\n          \"Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.\",\n        why: \"Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.\",\n        examples: [\n          'pm update pm-a1b2 --allow-audit-update --description \"...\" --author \"audit-agent\"',\n          'pm update pm-a1b2 --allow-audit-dep-update --dep \"...\" --author \"audit-agent\"',\n          'pm comments pm-a1b2 \"...\" --allow-audit-comment --author \"audit-agent\"',\n          'pm claim pm-a1b2 --author \"codex-agent\"',\n          'pm release pm-a1b2 --allow-audit-release --author \"reviewer\"',\n          'pm update pm-a1b2 --status in_progress --force',\n        ],\n        nextSteps: [\n          \"Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).\",\n          \"Use --allow-audit-dep-update for dependency-only non-owner additions.\",\n          \"Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.\",\n          \"Use --force for PM audits and systematic metadata updates performed by leads/maintainers.\",\n          \"Use --force when correcting known stale metadata after coordinating ownership changes.\",\n          'For non-terminal reassignment, prefer \"pm claim <ID> --author <you>\" before running other mutations.',\n          'For assignee handoff release workflows, prefer \"pm release <ID> --allow-audit-release --author <you>\" before using --force.',\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is locked\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"lock_conflict\",\n        title: \"Lock conflict\",\n        happened: message,\n        required: \"Wait for lock release, or use --force where supported if lock is stale and safe to override.\",\n        why: \"Locking protects item files from concurrent write races.\",\n        examples: ['pm update pm-a1b2 --status in_progress --force --author \"codex-agent\"'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const missingRequiredOption = message.match(/^Missing required option /);\n  const missingRequiredOptions = message.match(/^Missing required options /);\n  if (missingRequiredOption || missingRequiredOptions) {\n    const plural = Boolean(missingRequiredOptions);\n    const missingOptionFlag = !plural ? message.replace(/^Missing required option\\s+/, \"\").trim() : null;\n    const missingOptionRequired = missingOptionFlag\n      ? `Pass ${missingOptionFlag} with a valid value before running the command.`\n      : \"Provide the required option for this command invocation.\";\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"missing_required_option\",\n        title: plural ? \"Missing required options\" : missingOptionFlag ? `Missing required option ${missingOptionFlag}` : \"Missing required option\",\n        happened: message,\n        required: plural\n          ? \"Provide every required option for this command invocation.\"\n          : missingOptionRequired,\n        why: \"Required options define command intent and enforce deterministic write contracts.\",\n        examples: [\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --create-mode progressive',\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --status open --priority 1 --message \"Create task\" --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this task exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/example.ts,scope=project\" --test \"command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240\" --doc \"path=README.md,scope=project\"',\n        ],\n        nextSteps: [\n          'Run \"pm <command> --help\" to view required and recommended flags.',\n          \"For staged triage without placeholder linkage values, use --create-mode progressive.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"No update flags provided\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"no_update_fields\",\n        title: \"No update fields supplied\",\n        happened: \"The update command was called without any field-changing flags.\",\n        required:\n          \"Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.\",\n        why: \"pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.\",\n        examples: [\n          'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n          'pm update pm-a1b2 --description \"Clarified implementation scope\" --message \"Clarify task intent\"',\n          'pm append pm-a1b2 --body \"Detailed progress notes\" --message \"Append progress notes\"',\n        ],\n        nextSteps: [\n          \"Choose the item field you intend to change, then pair that change with --message for history context.\",\n          \"Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"Invalid \") || message.includes(\" must be \")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"invalid_argument_value\",\n        title: \"Invalid argument value\",\n        happened: message,\n        required: \"Use values that match documented command constraints.\",\n        why: \"Validation protects data consistency and deterministic behavior across commands.\",\n        examples: [\"pm create --help\", \"pm update --help\", \"pm calendar --help\"],\n        nextSteps: [\"Check allowed values in command help, then rerun with corrected input.\"],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  return applyPmCliErrorContext(\n    makeGuidanceMessage({\n      code: \"command_failed\",\n      title: \"Command failed\",\n      happened: message,\n      required: \"Adjust command input or tracker state and retry.\",\n      why: \"pm enforces explicit, deterministic contracts for data and command semantics.\",\n      examples: [\"pm --help\", \"pm <command> --help\"],\n    }),\n    rawMessage,\n    context,\n  );\n}\n\nfunction commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[] {\n  if (commandName === \"create\" && optionFlag.startsWith(\"--type\")) {\n    const firstAllowed = allowedTypes.split(\"|\")[0] || \"Task\";\n    return [\n      `pm create --title \"Example title\" --description \"Example description\" --type ${firstAllowed} --status open --priority 1 --message \"Create item\" --create-mode progressive`,\n    ];\n  }\n  if (commandName === \"update\") {\n    return ['pm update pm-a1b2 --status in_progress --message \"Start implementation\"'];\n  }\n  return [`pm ${commandName ?? \"<command>\"} --help`];\n}\n\nfunction buildCommanderErrorGuidance(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const requiredOption = message.match(/required option '([^']+)' not specified/);\n  if (requiredOption) {\n    const optionFlag = requiredOption[1];\n    const isType = optionFlag.startsWith(\"--type\");\n    return makeGuidanceMessage({\n      code: \"missing_required_option\",\n      title: `Missing required option ${optionFlag}`,\n      happened: `Commander rejected the command because ${optionFlag} was not provided.`,\n      required: `Pass ${optionFlag} with a valid value before running the command.`,\n      why: isType\n        ? \"--type selects item contract and policy routing, including required/disabled option rules.\"\n        : \"Required flags define mandatory command intent and prevent ambiguous execution.\",\n      examples: commandExampleForRequiredOption(commandName, optionFlag, allowedTypes),\n      nextSteps: isType\n        ? [`Allowed type values: ${allowedTypes}`, `Run \"pm ${commandName ?? \"create\"} --help --type <value>\" for type-aware policy details.`]\n        : [`Run \"pm ${commandName ?? \"<command>\"} --help\" for required option guidance.`],\n    });\n  }\n\n  const missingArgument = message.match(/missing required argument '([^']+)'/);\n  if (missingArgument) {\n    const argumentName = missingArgument[1];\n    return makeGuidanceMessage({\n      code: \"missing_required_argument\",\n      title: `Missing required argument ${argumentName}`,\n      happened: `Command invocation omitted positional argument ${argumentName}.`,\n      required: `Provide ${argumentName} in the expected command position.`,\n      why: \"Positional arguments identify the target entity or action context for the command.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n    });\n  }\n\n  const unknownOption = message.match(/unknown option '([^']+)'/);\n  if (unknownOption) {\n    const optionName = unknownOption[1];\n    if (commandName === \"update\" && (optionName === \"--file\" || optionName === \"--doc\")) {\n      return makeGuidanceMessage({\n        code: \"unsupported_update_option\",\n        title: `Unsupported option ${optionName} for update`,\n        happened: `pm update does not accept ${optionName} for linked artifact mutations.`,\n        required: \"Use dedicated linked-artifact commands instead of pm update for files/docs changes.\",\n        why: \"pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.\",\n        examples: [\n          'pm files pm-a1b2 --add \"path=src/cli/main.ts,scope=project,note=implementation surface\"',\n          'pm docs pm-a1b2 --add \"path=README.md,scope=project,note=user-facing contract\"',\n        ],\n        nextSteps: ['Run \"pm files --help\" and \"pm docs --help\" for add/remove payload formats.'],\n      });\n    }\n    return makeGuidanceMessage({\n      code: \"unknown_option\",\n      title: `Unknown option ${optionName}`,\n      happened: `Commander does not recognize option ${optionName} for this command path.`,\n      required: \"Use supported options only, or move option to the correct subcommand.\",\n      why: \"Option contracts are command-specific and intentionally validated.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n    });\n  }\n\n  const unknownCommand = message.match(/unknown command '([^']+)'/);\n  if (unknownCommand) {\n    const commandToken = unknownCommand[1];\n    const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);\n    const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);\n    return makeGuidanceMessage({\n      code: \"unknown_command\",\n      title: `Unknown command ${commandToken}`,\n      happened: `pm does not expose command path \"${commandToken}\" in current runtime configuration.`,\n      required: \"Use a valid command name or subcommand path.\",\n      why: \"Command registry includes core commands plus active extension command handlers.\",\n      examples: runtimeExamples ?? [\"pm --help\"],\n      nextSteps: runtimeNextSteps ?? [\"Verify spelling and active extensions, then rerun.\"],\n    });\n  }\n\n  return makeGuidanceMessage({\n    code: \"invalid_command_usage\",\n    title: \"Invalid command usage\",\n    happened: message,\n    required: \"Use the command with valid arguments and options.\",\n    why: \"Commander validates CLI contracts before execution.\",\n    examples: [\"pm --help\", `pm ${commandName ?? \"<command>\"} --help`],\n  });\n}\n\nexport function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string {\n  return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification {\n  return guidanceToClassification(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);\n}\n\nexport function formatCommanderErrorForDisplay(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): string {\n  return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function classifyCommanderError(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): ErrorClassification {\n  return guidanceToClassification(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function formatCommanderErrorForJson(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  exitCode: number,\n  context?: CommanderGuidanceContext,\n): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);\n}\n\nexport function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope {\n  const guidance = buildUnknownErrorGuidance(rawMessage);\n  return guidanceToJsonEnvelope(guidance, exitCode);\n}\n\nfunction buildUnknownErrorGuidance(rawMessage: string): GuidanceMessage {\n  return makeGuidanceMessage({\n    code: \"unknown_error\",\n    title: \"Unhandled error\",\n    happened: normalizeMessage(rawMessage),\n    required: \"Inspect command input and runtime state, then retry.\",\n    why: \"Unexpected runtime failures can occur from environment or extension-level issues.\",\n    examples: [\"pm --help\", \"pm health --json\"],\n  });\n}\n\nexport function classifyUnknownError(rawMessage: string): ErrorClassification {\n  return guidanceToClassification(buildUnknownErrorGuidance(rawMessage));\n}\n"]}
+{"version":3,"file":"error-guidance.js","sourceRoot":"/","sources":["cli/error-guidance.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PmCliErrorContext, PmCliErrorRecoveryPayload } from \"../core/shared/errors.js\";\nimport { renderPmCommand } from \"./argv-utils.js\";\n\ninterface GuidanceMessage {\n  code: string;\n  type: string;\n  title: string;\n  happened: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  nextSteps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface JsonErrorEnvelope {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  exit_code: number;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface ErrorClassification {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface CommanderGuidanceContext {\n  unknownCommandExamples?: string[];\n  unknownCommandNextSteps?: string[];\n  attemptedCommand?: string;\n  normalizedInvocationArgs?: string[];\n  providedOptionFlags?: string[];\n  unknownOptionSuggestions?: string[];\n  suggestedRetryCommand?: string;\n}\n\nfunction errorType(code: string): string {\n  return `urn:pm-cli:error:${code}`;\n}\n\nfunction makeGuidanceMessage(params: Omit<GuidanceMessage, \"type\">): GuidanceMessage {\n  return {\n    ...params,\n    type: errorType(params.code),\n  };\n}\n\nfunction renderList(title: string, entries: string[]): string[] {\n  if (entries.length === 0) {\n    return [];\n  }\n  return [title, ...entries.map((entry) => `  - ${entry}`)];\n}\n\nfunction normalizeRecoveryPayload(payload: PmCliErrorRecoveryPayload | undefined): PmCliErrorRecoveryPayload | undefined {\n  if (!payload || typeof payload !== \"object\") {\n    return undefined;\n  }\n  const normalized: PmCliErrorRecoveryPayload = {};\n  if (typeof payload.attempted_command === \"string\" && payload.attempted_command.trim().length > 0) {\n    normalized.attempted_command = payload.attempted_command.trim();\n  }\n  if (Array.isArray(payload.normalized_args)) {\n    const args = payload.normalized_args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (args.length > 0) {\n      normalized.normalized_args = args;\n    }\n  }\n  if (Array.isArray(payload.provided_fields)) {\n    const fields = payload.provided_fields.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (fields.length > 0) {\n      normalized.provided_fields = fields;\n    }\n  }\n  if (Array.isArray(payload.missing)) {\n    const missing = payload.missing.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (missing.length > 0) {\n      normalized.missing = missing;\n    }\n  }\n  if (typeof payload.suggested_retry === \"string\" && payload.suggested_retry.trim().length > 0) {\n    normalized.suggested_retry = payload.suggested_retry.trim();\n  }\n  return Object.keys(normalized).length > 0 ? normalized : undefined;\n}\n\nfunction renderRecoveryBundle(recovery: PmCliErrorRecoveryPayload | undefined): string[] {\n  const normalized = normalizeRecoveryPayload(recovery);\n  if (!normalized) {\n    return [];\n  }\n  const lines = [\"Recovery bundle:\"];\n  if (normalized.attempted_command) {\n    lines.push(`  attempted_command: ${normalized.attempted_command}`);\n  }\n  if (normalized.normalized_args && normalized.normalized_args.length > 0) {\n    lines.push(`  normalized_args: ${normalized.normalized_args.join(\" \")}`);\n  }\n  if (normalized.provided_fields && normalized.provided_fields.length > 0) {\n    lines.push(`  provided_fields: ${normalized.provided_fields.join(\", \")}`);\n  }\n  if (normalized.missing && normalized.missing.length > 0) {\n    lines.push(`  missing: ${normalized.missing.join(\", \")}`);\n  }\n  if (normalized.suggested_retry) {\n    lines.push(`  suggested_retry: ${normalized.suggested_retry}`);\n  }\n  return lines;\n}\n\nexport function renderGuidanceMessage(message: GuidanceMessage): string {\n  const lines: string[] = [\n    `Error: ${message.title}`,\n    \"\",\n    \"What happened:\",\n    `  ${message.happened}`,\n    \"\",\n    \"What is required:\",\n    `  ${message.required}`,\n  ];\n  if (message.why) {\n    lines.push(\"\", \"Why:\");\n    lines.push(`  ${message.why}`);\n  }\n  if (message.examples && message.examples.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Examples:\", message.examples));\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Next steps:\", message.nextSteps));\n  }\n  const recoveryLines = renderRecoveryBundle(message.recovery);\n  if (recoveryLines.length > 0) {\n    lines.push(\"\");\n    lines.push(...recoveryLines);\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: number): JsonErrorEnvelope {\n  const payload: JsonErrorEnvelope = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n    exit_code: exitCode,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  if (message.recovery) {\n    payload.recovery = message.recovery;\n  }\n  return payload;\n}\n\nfunction guidanceToClassification(message: GuidanceMessage): ErrorClassification {\n  const payload: ErrorClassification = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  if (message.recovery) {\n    payload.recovery = message.recovery;\n  }\n  return payload;\n}\n\nfunction normalizeMessage(message: string): string {\n  return message.replace(/\\(outputHelp\\)/g, \"\").trim();\n}\n\nfunction normalizeContextList(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildFallbackTitleFromMessage(message: string): string | undefined {\n  const firstLine = message.split(/\\r?\\n/)[0]?.trim() ?? \"\";\n  if (firstLine.length === 0) {\n    return undefined;\n  }\n  if (firstLine.length <= 120) {\n    return firstLine;\n  }\n  return `${firstLine.slice(0, 117)}...`;\n}\n\nfunction applyPmCliErrorContext(\n  guidance: GuidanceMessage,\n  rawMessage: string,\n  context: PmCliErrorContext | undefined,\n): GuidanceMessage {\n  if (!context) {\n    return guidance;\n  }\n  const normalizedRawMessage = normalizeMessage(rawMessage);\n  const code = typeof context.code === \"string\" && context.code.trim().length > 0 ? context.code.trim() : guidance.code;\n  const type = typeof context.type === \"string\" && context.type.trim().length > 0 ? context.type.trim() : errorType(code);\n  const examples = normalizeContextList(context.examples) ?? guidance.examples;\n  const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;\n  const fallbackTitle = guidance.code === \"command_failed\" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;\n  const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;\n  return {\n    ...guidance,\n    code,\n    type,\n    title: fallbackTitle ?? guidance.title,\n    happened: normalizedRawMessage.length > 0 ? normalizedRawMessage : guidance.happened,\n    required: typeof context.required === \"string\" && context.required.trim().length > 0 ? context.required.trim() : guidance.required,\n    why: typeof context.why === \"string\" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,\n    examples,\n    nextSteps,\n    recovery,\n  };\n}\n\nfunction buildPmCliErrorGuidance(rawMessage: string, context?: PmCliErrorContext): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\\. Run pm init first\\.$/);\n  if (trackerNotInitialized) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"tracker_not_initialized\",\n        title: \"Tracker is not initialized\",\n        happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,\n        required: \"Initialize tracker storage before running this command.\",\n        why: \"Most commands require settings and tracker directories created by pm init.\",\n        examples: [\"pm init\", \"pm init acme\"],\n        nextSteps: ['Run \"pm init\", then rerun your original command.'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const itemNotFound = message.match(/^Item ([^ ]+) not found$/);\n  if (itemNotFound) {\n    const badId = itemNotFound[1];\n    const isPlaceholder = /^(undefined|null|<.*>|\\[.*\\]|{.*}|)$/.test(badId);\n    const happened = isPlaceholder\n      ? `The item ID \"${badId}\" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.`\n      : `No item with id \"${badId}\" exists in the active tracker scope.`;\n    const nextSteps = isPlaceholder\n      ? [\n          \"Check that the variable holding the item ID is defined before passing it to pm.\",\n          'Use \"pm list-open --limit 20\" to find valid IDs.',\n        ]\n      : [\"Confirm the active --path/PM_PATH scope, then retry with a valid id.\"];\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"item_not_found\",\n        title: \"Item ID not found\",\n        happened,\n        required: \"Use an existing item ID from current tracker data.\",\n        why: \"Mutation and read commands operate only on known IDs.\",\n        examples: ['pm list-open --limit 20', 'pm search \"<keyword>\" --limit 10'],\n        nextSteps,\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is assigned to\") && message.includes(\"Use --force to override\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"ownership_conflict\",\n        title: \"Ownership conflict\",\n        happened: message,\n        required:\n          \"Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.\",\n        why: \"Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.\",\n        examples: [\n          'pm update pm-a1b2 --allow-audit-update --description \"...\" --author \"audit-agent\"',\n          'pm update pm-a1b2 --allow-audit-dep-update --dep \"...\" --author \"audit-agent\"',\n          'pm comments pm-a1b2 \"...\" --allow-audit-comment --author \"audit-agent\"',\n          'pm claim pm-a1b2 --author \"codex-agent\"',\n          'pm release pm-a1b2 --allow-audit-release --author \"reviewer\"',\n          'pm update pm-a1b2 --status in_progress --force',\n        ],\n        nextSteps: [\n          \"Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).\",\n          \"Use --allow-audit-dep-update for dependency-only non-owner additions.\",\n          \"Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.\",\n          \"Use --force for PM audits and systematic metadata updates performed by leads/maintainers.\",\n          \"Use --force when correcting known stale metadata after coordinating ownership changes.\",\n          'For non-terminal reassignment, prefer \"pm claim <ID> --author <you>\" before running other mutations.',\n          'For assignee handoff release workflows, prefer \"pm release <ID> --allow-audit-release --author <you>\" before using --force.',\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is locked\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"lock_conflict\",\n        title: \"Lock conflict\",\n        happened: message,\n        required: \"Wait for lock release, or use --force where supported if lock is stale and safe to override.\",\n        why: \"Locking protects item files from concurrent write races.\",\n        examples: ['pm update pm-a1b2 --status in_progress --force --author \"codex-agent\"'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const missingRequiredOption = message.match(/^Missing required option /);\n  const missingRequiredOptions = message.match(/^Missing required options /);\n  if (missingRequiredOption || missingRequiredOptions) {\n    const plural = Boolean(missingRequiredOptions);\n    const missingOptionFlag = !plural ? message.replace(/^Missing required option\\s+/, \"\").trim() : null;\n    const missingOptionRequired = missingOptionFlag\n      ? `Pass ${missingOptionFlag} with a valid value before running the command.`\n      : \"Provide the required option for this command invocation.\";\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"missing_required_option\",\n        title: plural ? \"Missing required options\" : missingOptionFlag ? `Missing required option ${missingOptionFlag}` : \"Missing required option\",\n        happened: message,\n        required: plural\n          ? \"Provide every required option for this command invocation.\"\n          : missingOptionRequired,\n        why: \"Required options define command intent and enforce deterministic write contracts.\",\n        examples: [\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --create-mode progressive',\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --status open --priority 1 --message \"Create task\" --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this task exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/example.ts,scope=project\" --test \"command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240\" --doc \"path=README.md,scope=project\"',\n        ],\n        nextSteps: [\n          'Run \"pm <command> --help\" to view required and recommended flags.',\n          \"For staged triage without placeholder linkage values, use --create-mode progressive.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"No update flags provided\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"no_update_fields\",\n        title: \"No update fields supplied\",\n        happened: \"The update command was called without any field-changing flags.\",\n        required:\n          \"Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.\",\n        why: \"pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.\",\n        examples: [\n          'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n          'pm update pm-a1b2 --description \"Clarified implementation scope\" --message \"Clarify task intent\"',\n          'pm append pm-a1b2 --body \"Detailed progress notes\" --message \"Append progress notes\"',\n        ],\n        nextSteps: [\n          \"Choose the item field you intend to change, then pair that change with --message for history context.\",\n          \"Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"Invalid \") || message.includes(\" must be \")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"invalid_argument_value\",\n        title: \"Invalid argument value\",\n        happened: message,\n        required: \"Use values that match documented command constraints.\",\n        why: \"Validation protects data consistency and deterministic behavior across commands.\",\n        examples: [\"pm create --help\", \"pm update --help\", \"pm calendar --help\"],\n        nextSteps: [\"Check allowed values in command help, then rerun with corrected input.\"],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  return applyPmCliErrorContext(\n    makeGuidanceMessage({\n      code: \"command_failed\",\n      title: \"Command failed\",\n      happened: message,\n      required: \"Adjust command input or tracker state and retry.\",\n      why: \"pm enforces explicit, deterministic contracts for data and command semantics.\",\n      examples: [\"pm --help\", \"pm <command> --help\"],\n    }),\n    rawMessage,\n    context,\n  );\n}\n\nfunction commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[] {\n  if (commandName === \"create\" && optionFlag.startsWith(\"--type\")) {\n    const firstAllowed = allowedTypes.split(\"|\")[0] || \"Task\";\n    return [\n      `pm create --title \"Example title\" --description \"Example description\" --type ${firstAllowed} --status open --priority 1 --message \"Create item\" --create-mode progressive`,\n    ];\n  }\n  if (commandName === \"update\") {\n    return ['pm update pm-a1b2 --status in_progress --message \"Start implementation\"'];\n  }\n  return [`pm ${commandName ?? \"<command>\"} --help`];\n}\n\nfunction normalizeRequiredOptionLabel(rawValue: string): string {\n  const normalized = rawValue.trim();\n  const firstLongFlag = normalized.match(/--[A-Za-z0-9][A-Za-z0-9_-]*/)?.[0];\n  return firstLongFlag ?? normalized;\n}\n\nfunction renderPmCommandFromArgs(argv: string[] | undefined): string | undefined {\n  if (!Array.isArray(argv) || argv.length === 0) {\n    return undefined;\n  }\n  return renderPmCommand(argv);\n}\n\nfunction normalizeOptionFlags(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildCommanderRecoveryPayload(\n  context: CommanderGuidanceContext | undefined,\n  overrides: Partial<PmCliErrorRecoveryPayload> = {},\n): PmCliErrorRecoveryPayload | undefined {\n  const providedFields = normalizeOptionFlags(context?.providedOptionFlags);\n  const normalizedArgs =\n    Array.isArray(context?.normalizedInvocationArgs) && context?.normalizedInvocationArgs.length > 0\n      ? context.normalizedInvocationArgs\n      : undefined;\n  const attemptedCommand = typeof context?.attemptedCommand === \"string\" ? context.attemptedCommand : renderPmCommandFromArgs(normalizedArgs);\n  const retryCommand = typeof context?.suggestedRetryCommand === \"string\" ? context.suggestedRetryCommand : undefined;\n  return normalizeRecoveryPayload({\n    attempted_command: attemptedCommand,\n    normalized_args: normalizedArgs,\n    provided_fields: providedFields,\n    suggested_retry: retryCommand,\n    ...overrides,\n  });\n}\n\nfunction appendIfMissing(entries: string[], value: string | undefined): string[] {\n  if (!value || entries.includes(value)) {\n    return entries;\n  }\n  return [...entries, value];\n}\n\nfunction buildCommanderErrorGuidance(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const requiredOption = message.match(/required option '([^']+)' not specified/);\n  if (requiredOption) {\n    const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);\n    const isType = optionFlag.startsWith(\"--type\");\n    const retryCommand = context?.suggestedRetryCommand;\n    const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);\n    const missing = [optionFlag];\n    const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);\n    const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;\n    const nextStepsBase = isType\n      ? [`Allowed type values: ${allowedTypes}`, `Run \"pm ${commandName ?? \"create\"} --help --type <value>\" for type-aware policy details.`]\n      : [`Run \"pm ${commandName ?? \"<command>\"} --help\" for required option guidance.`];\n    const nextStepsWithRetry = retryCommand\n      ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`)\n      : nextStepsBase;\n    const nextSteps =\n      providedFlags && providedFlags.length > 0\n        ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(\", \")}`)\n        : nextStepsWithRetry;\n    return makeGuidanceMessage({\n      code: \"missing_required_option\",\n      title: `Missing required option ${optionFlag}`,\n      happened: `Commander rejected the command because ${optionFlag} was not provided.`,\n      required: `Pass ${optionFlag} with a valid value before running the command.`,\n      why: isType\n        ? \"--type selects item contract and policy routing, including required/disabled option rules.\"\n        : \"Required flags define mandatory command intent and prevent ambiguous execution.\",\n      examples: examplesWithRetry,\n      nextSteps,\n      recovery: buildCommanderRecoveryPayload(context, { missing }),\n    });\n  }\n\n  const missingArgument = message.match(/missing required argument '([^']+)'/);\n  if (missingArgument) {\n    const argumentName = missingArgument[1];\n    return makeGuidanceMessage({\n      code: \"missing_required_argument\",\n      title: `Missing required argument ${argumentName}`,\n      happened: `Command invocation omitted positional argument ${argumentName}.`,\n      required: `Provide ${argumentName} in the expected command position.`,\n      why: \"Positional arguments identify the target entity or action context for the command.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n      recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] }),\n    });\n  }\n\n  const unknownOption = message.match(/unknown option '([^']+)'/);\n  if (unknownOption) {\n    const optionName = unknownOption[1];\n    const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);\n    const retryCommand = context?.suggestedRetryCommand;\n    if (commandName === \"update\" && (optionName === \"--file\" || optionName === \"--doc\")) {\n      return makeGuidanceMessage({\n        code: \"unsupported_update_option\",\n        title: `Unsupported option ${optionName} for update`,\n        happened: `pm update does not accept ${optionName} for linked artifact mutations.`,\n        required: \"Use dedicated linked-artifact commands instead of pm update for files/docs changes.\",\n        why: \"pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.\",\n        examples: [\n          'pm files pm-a1b2 --add \"path=src/cli/main.ts,scope=project,note=implementation surface\"',\n          'pm docs pm-a1b2 --add \"path=README.md,scope=project,note=user-facing contract\"',\n        ],\n        nextSteps: ['Run \"pm files --help\" and \"pm docs --help\" for add/remove payload formats.'],\n        recovery: buildCommanderRecoveryPayload(context, {\n          missing: suggestions,\n        }),\n      });\n    }\n    const nextSteps = [\n      \"Run command help to confirm the exact option contracts for this command path.\",\n      ...(suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(\", \")}`] : []),\n      ...(retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []),\n    ];\n    const examples = [\n      ...(retryCommand ? [retryCommand] : []),\n      `pm ${commandName ?? \"<command>\"} --help`,\n    ];\n    return makeGuidanceMessage({\n      code: \"unknown_option\",\n      title: `Unknown option ${optionName}`,\n      happened: `Commander does not recognize option ${optionName} for this command path.`,\n      required: \"Use supported options only, or move option to the correct subcommand.\",\n      why: \"Option contracts are command-specific and intentionally validated.\",\n      examples,\n      nextSteps,\n      recovery: buildCommanderRecoveryPayload(context, {\n        missing: suggestions,\n      }),\n    });\n  }\n\n  const unknownCommand = message.match(/unknown command '([^']+)'/);\n  if (unknownCommand) {\n    const commandToken = unknownCommand[1];\n    const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);\n    const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);\n    return makeGuidanceMessage({\n      code: \"unknown_command\",\n      title: `Unknown command ${commandToken}`,\n      happened: `pm does not expose command path \"${commandToken}\" in current runtime configuration.`,\n      required: \"Use a valid command name or subcommand path.\",\n      why: \"Command registry includes core commands plus active extension command handlers.\",\n      examples: runtimeExamples ?? [\"pm --help\"],\n      nextSteps: runtimeNextSteps ?? [\"Verify spelling and active extensions, then rerun.\"],\n      recovery: buildCommanderRecoveryPayload(context),\n    });\n  }\n\n  return makeGuidanceMessage({\n    code: \"invalid_command_usage\",\n    title: \"Invalid command usage\",\n    happened: message,\n    required: \"Use the command with valid arguments and options.\",\n    why: \"Commander validates CLI contracts before execution.\",\n    examples: [\"pm --help\", `pm ${commandName ?? \"<command>\"} --help`],\n    recovery: buildCommanderRecoveryPayload(context),\n  });\n}\n\nexport function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string {\n  return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification {\n  return guidanceToClassification(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);\n}\n\nexport function formatCommanderErrorForDisplay(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): string {\n  return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function classifyCommanderError(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): ErrorClassification {\n  return guidanceToClassification(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function formatCommanderErrorForJson(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  exitCode: number,\n  context?: CommanderGuidanceContext,\n): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);\n}\n\nexport function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope {\n  const guidance = buildUnknownErrorGuidance(rawMessage);\n  return guidanceToJsonEnvelope(guidance, exitCode);\n}\n\nfunction buildUnknownErrorGuidance(rawMessage: string): GuidanceMessage {\n  return makeGuidanceMessage({\n    code: \"unknown_error\",\n    title: \"Unhandled error\",\n    happened: normalizeMessage(rawMessage),\n    required: \"Inspect command input and runtime state, then retry.\",\n    why: \"Unexpected runtime failures can occur from environment or extension-level issues.\",\n    examples: [\"pm --help\", \"pm health --json\"],\n  });\n}\n\nexport function classifyUnknownError(rawMessage: string): ErrorClassification {\n  return guidanceToClassification(buildUnknownErrorGuidance(rawMessage));\n}\n"]}

package/dist/cli/guide-topics.d.ts

@@ -0,0 +1,25 @@
+export interface GuideDocReference {
+    path: string;
+    purpose: string;
+    optional?: boolean;
+}
+export interface GuideWorkflowTemplate {
+    name: string;
+    goal: string;
+    prompt: string;
+    commands: string[];
+}
+export interface GuideTopicDefinition {
+    id: string;
+    aliases: string[];
+    title: string;
+    summary: string;
+    intent: string;
+    commands: string[];
+    workflows: GuideWorkflowTemplate[];
+    docs: GuideDocReference[];
+    related: string[];
+}
+export declare function listGuideTopics(): GuideTopicDefinition[];
+export declare function listGuideTopicIds(): string[];
+export declare function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null;