@unbrained/pm-cli 2026.5.2 → 2026.5.3-6

package/dist/cli/commands/test-runs.js

@@ -1,11 +1,11 @@
 import os from "node:os";
 import { pathExists } from "../../core/fs/fs-utils.js";
-import { parseOptionalNumber } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { getBackgroundTestRunStatus, listBackgroundTestRuns, readBackgroundTestRunLogs, resumeBackgroundTestRun, runBackgroundTestRunWorker, spawnBackgroundTestRunWorker, startBackgroundTestRun, stopBackgroundTestRun, } from "../../core/test/background-runs.js";
 import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
+import { parseLimit } from "../shared-parsers.js";
 const BACKGROUND_STATUS_VALUES = ["queued", "running", "passed", "failed", "stopped", "canceled"];
 const BACKGROUND_STREAM_VALUES = ["stdout", "stderr", "both"];
 function normalizeStatus(value) {
@@ -28,16 +28,6 @@ function normalizeStream(value) {
     }
     throw new PmCliError(`Invalid --stream value "${value}"`, EXIT_CODE.USAGE);
 }
-function parseLimit(value, label) {
-    if (value === undefined) {
-        return undefined;
-    }
-    const parsed = parseOptionalNumber(value, label);
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        throw new PmCliError(`${label} must be a non-negative number`, EXIT_CODE.USAGE);
-    }
-    return Math.floor(parsed);
-}
 function resolveWhoamiFallback() {
     try {
         const username = os.userInfo().username.trim();

package/dist/cli/commands/test-runs.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-runs.js","sourceRoot":"/","sources":["cli/commands/test-runs.ts"],"names":[],"mappings":"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","sourcesContent":["import os from \"node:os\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { parseOptionalNumber } from \"../../core/item/parse.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n  type BackgroundLogStream,\n  type BackgroundTestRunKind,\n  type BackgroundTestRunStatus,\n  getBackgroundTestRunStatus,\n  listBackgroundTestRuns,\n  readBackgroundTestRunLogs,\n  resumeBackgroundTestRun,\n  runBackgroundTestRunWorker,\n  spawnBackgroundTestRunWorker,\n  startBackgroundTestRun,\n  stopBackgroundTestRun,\n} from \"../../core/test/background-runs.js\";\nimport { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\n\nconst BACKGROUND_STATUS_VALUES: readonly BackgroundTestRunStatus[] = [\"queued\", \"running\", \"passed\", \"failed\", \"stopped\", \"canceled\"];\nconst BACKGROUND_STREAM_VALUES: readonly BackgroundLogStream[] = [\"stdout\", \"stderr\", \"both\"];\n\nfunction normalizeStatus(value: string | undefined): BackgroundTestRunStatus | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STATUS_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundTestRunStatus;\n  }\n  throw new PmCliError(`Invalid --status value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction normalizeStream(value: string | undefined): BackgroundLogStream {\n  if (value === undefined || value.trim().length === 0) {\n    return \"stderr\";\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STREAM_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundLogStream;\n  }\n  throw new PmCliError(`Invalid --stream value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction parseLimit(value: string | undefined, label: string): number | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const parsed = parseOptionalNumber(value, label);\n  if (!Number.isFinite(parsed) || parsed < 0) {\n    throw new PmCliError(`${label} must be a non-negative number`, EXIT_CODE.USAGE);\n  }\n  return Math.floor(parsed);\n}\n\nfunction resolveWhoamiFallback(): string | undefined {\n  try {\n    const username = os.userInfo().username.trim();\n    if (username.length > 0) {\n      return username;\n    }\n  } catch {\n    // Fall back to environment-derived attribution.\n  }\n  return undefined;\n}\n\nfunction resolveRequestedBy(author: string | undefined, fallback: string): string {\n  const candidates = [\n    author,\n    process.env.PM_AUTHOR,\n    fallback,\n    process.env.USER,\n    process.env.LOGNAME,\n    process.env.USERNAME,\n    resolveWhoamiFallback(),\n  ];\n  for (const candidate of candidates) {\n    if (typeof candidate !== \"string\") {\n      continue;\n    }\n    const trimmed = candidate.trim();\n    if (trimmed.length > 0) {\n      return trimmed;\n    }\n  }\n  return \"unknown\";\n}\n\nasync function ensureInitialized(pmRoot: string): Promise<void> {\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n}\n\nexport interface StartBackgroundRunCommandOptions {\n  kind: BackgroundTestRunKind;\n  commandArgs: string[];\n  targetId?: string;\n  statusFilter?: string;\n  author?: string;\n  noExtensions?: boolean;\n}\n\nexport interface StartBackgroundRunResult {\n  started: boolean;\n  duplicate_of?: string;\n  run: unknown;\n}\n\nexport async function runStartBackgroundRun(\n  options: StartBackgroundRunCommandOptions,\n  global: GlobalOptions,\n): Promise<StartBackgroundRunResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const globalPmRoot = resolveGlobalPmRoot(process.cwd());\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(options.author, settings.author_default);\n  const started = await startBackgroundTestRun({\n    pmRoot,\n    globalPmRoot,\n    kind: options.kind,\n    commandArgs: options.commandArgs,\n    requestedBy,\n    targetId: options.targetId,\n    statusFilter: options.statusFilter,\n  });\n  if (!started.started) {\n    return {\n      started: false,\n      duplicate_of: started.duplicate_of,\n      run: started.run,\n    };\n  }\n  const spawned = await spawnBackgroundTestRunWorker({\n    pmRoot,\n    runId: started.run.id,\n    noExtensions: options.noExtensions === true,\n  });\n  return {\n    started: true,\n    run: spawned,\n  };\n}\n\nexport interface TestRunsListCommandOptions {\n  status?: string;\n  limit?: string;\n}\n\nexport async function runTestRunsList(options: TestRunsListCommandOptions, global: GlobalOptions): Promise<{\n  runs: unknown[];\n  count: number;\n  filters: {\n    status?: BackgroundTestRunStatus;\n    limit?: number;\n  };\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = normalizeStatus(options.status);\n  const limit = parseLimit(options.limit, \"limit\");\n  const runs = await listBackgroundTestRuns(pmRoot, { status, limit });\n  return {\n    runs,\n    count: runs.length,\n    filters: {\n      status,\n      limit,\n    },\n  };\n}\n\nexport async function runTestRunsStatus(runId: string, global: GlobalOptions): Promise<{\n  run: unknown;\n  health: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = await getBackgroundTestRunStatus(pmRoot, runId);\n  return {\n    run: status.run,\n    health: status.health,\n  };\n}\n\nexport interface TestRunsLogsCommandOptions {\n  stream?: string;\n  tail?: string;\n}\n\nexport async function runTestRunsLogs(\n  runId: string,\n  options: TestRunsLogsCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  stream: BackgroundLogStream;\n  tail: number;\n  stdout: string[];\n  stderr: string[];\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stream = normalizeStream(options.stream);\n  const tail = parseLimit(options.tail, \"tail\");\n  const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);\n  return {\n    run: logs.run,\n    stream: logs.stream,\n    tail: logs.tail,\n    stdout: logs.stdout,\n    stderr: logs.stderr,\n  };\n}\n\nexport interface TestRunsStopCommandOptions {\n  force?: boolean;\n}\n\nexport async function runTestRunsStop(\n  runId: string,\n  options: TestRunsStopCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  signal_sent: \"SIGTERM\" | \"SIGKILL\" | \"none\";\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stopped = await stopBackgroundTestRun(pmRoot, runId, options.force === true);\n  return {\n    run: stopped.run,\n    signal_sent: stopped.signal_sent,\n  };\n}\n\nexport interface TestRunsResumeCommandOptions {\n  author?: string;\n  noExtensions?: boolean;\n}\n\nexport async function runTestRunsResume(\n  runId: string,\n  options: TestRunsResumeCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  resumed_from: string;\n  run: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(options.author, settings.author_default);\n  const resumed = await resumeBackgroundTestRun(pmRoot, runId, requestedBy, options.noExtensions === true);\n  return {\n    resumed_from: runId,\n    run: resumed,\n  };\n}\n\nexport async function runTestRunsWorker(runId: string, global: GlobalOptions): Promise<{\n  id: string;\n  status: BackgroundTestRunStatus;\n  exit_code?: number;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const finished = await runBackgroundTestRunWorker(pmRoot, runId, global.noExtensions === true);\n  return {\n    id: finished.id,\n    status: finished.status,\n    exit_code: finished.exit_code,\n  };\n}\n"]}
+{"version":3,"file":"test-runs.js","sourceRoot":"/","sources":["cli/commands/test-runs.ts"],"names":[],"mappings":"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","sourcesContent":["import os from \"node:os\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n  type BackgroundLogStream,\n  type BackgroundTestRunKind,\n  type BackgroundTestRunStatus,\n  getBackgroundTestRunStatus,\n  listBackgroundTestRuns,\n  readBackgroundTestRunLogs,\n  resumeBackgroundTestRun,\n  runBackgroundTestRunWorker,\n  spawnBackgroundTestRunWorker,\n  startBackgroundTestRun,\n  stopBackgroundTestRun,\n} from \"../../core/test/background-runs.js\";\nimport { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\n\nconst BACKGROUND_STATUS_VALUES: readonly BackgroundTestRunStatus[] = [\"queued\", \"running\", \"passed\", \"failed\", \"stopped\", \"canceled\"];\nconst BACKGROUND_STREAM_VALUES: readonly BackgroundLogStream[] = [\"stdout\", \"stderr\", \"both\"];\n\nfunction normalizeStatus(value: string | undefined): BackgroundTestRunStatus | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STATUS_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundTestRunStatus;\n  }\n  throw new PmCliError(`Invalid --status value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction normalizeStream(value: string | undefined): BackgroundLogStream {\n  if (value === undefined || value.trim().length === 0) {\n    return \"stderr\";\n  }\n  const normalized = value.trim().toLowerCase();\n  if ((BACKGROUND_STREAM_VALUES as readonly string[]).includes(normalized)) {\n    return normalized as BackgroundLogStream;\n  }\n  throw new PmCliError(`Invalid --stream value \"${value}\"`, EXIT_CODE.USAGE);\n}\n\nfunction resolveWhoamiFallback(): string | undefined {\n  try {\n    const username = os.userInfo().username.trim();\n    if (username.length > 0) {\n      return username;\n    }\n  } catch {\n    // Fall back to environment-derived attribution.\n  }\n  return undefined;\n}\n\nfunction resolveRequestedBy(author: string | undefined, fallback: string): string {\n  const candidates = [\n    author,\n    process.env.PM_AUTHOR,\n    fallback,\n    process.env.USER,\n    process.env.LOGNAME,\n    process.env.USERNAME,\n    resolveWhoamiFallback(),\n  ];\n  for (const candidate of candidates) {\n    if (typeof candidate !== \"string\") {\n      continue;\n    }\n    const trimmed = candidate.trim();\n    if (trimmed.length > 0) {\n      return trimmed;\n    }\n  }\n  return \"unknown\";\n}\n\nasync function ensureInitialized(pmRoot: string): Promise<void> {\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n}\n\nexport interface StartBackgroundRunCommandOptions {\n  kind: BackgroundTestRunKind;\n  commandArgs: string[];\n  targetId?: string;\n  statusFilter?: string;\n  author?: string;\n  noExtensions?: boolean;\n}\n\nexport interface StartBackgroundRunResult {\n  started: boolean;\n  duplicate_of?: string;\n  run: unknown;\n}\n\nexport async function runStartBackgroundRun(\n  options: StartBackgroundRunCommandOptions,\n  global: GlobalOptions,\n): Promise<StartBackgroundRunResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const globalPmRoot = resolveGlobalPmRoot(process.cwd());\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(options.author, settings.author_default);\n  const started = await startBackgroundTestRun({\n    pmRoot,\n    globalPmRoot,\n    kind: options.kind,\n    commandArgs: options.commandArgs,\n    requestedBy,\n    targetId: options.targetId,\n    statusFilter: options.statusFilter,\n  });\n  if (!started.started) {\n    return {\n      started: false,\n      duplicate_of: started.duplicate_of,\n      run: started.run,\n    };\n  }\n  const spawned = await spawnBackgroundTestRunWorker({\n    pmRoot,\n    runId: started.run.id,\n    noExtensions: options.noExtensions === true,\n  });\n  return {\n    started: true,\n    run: spawned,\n  };\n}\n\nexport interface TestRunsListCommandOptions {\n  status?: string;\n  limit?: string;\n}\n\nexport async function runTestRunsList(options: TestRunsListCommandOptions, global: GlobalOptions): Promise<{\n  runs: unknown[];\n  count: number;\n  filters: {\n    status?: BackgroundTestRunStatus;\n    limit?: number;\n  };\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = normalizeStatus(options.status);\n  const limit = parseLimit(options.limit, \"limit\");\n  const runs = await listBackgroundTestRuns(pmRoot, { status, limit });\n  return {\n    runs,\n    count: runs.length,\n    filters: {\n      status,\n      limit,\n    },\n  };\n}\n\nexport async function runTestRunsStatus(runId: string, global: GlobalOptions): Promise<{\n  run: unknown;\n  health: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const status = await getBackgroundTestRunStatus(pmRoot, runId);\n  return {\n    run: status.run,\n    health: status.health,\n  };\n}\n\nexport interface TestRunsLogsCommandOptions {\n  stream?: string;\n  tail?: string;\n}\n\nexport async function runTestRunsLogs(\n  runId: string,\n  options: TestRunsLogsCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  stream: BackgroundLogStream;\n  tail: number;\n  stdout: string[];\n  stderr: string[];\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stream = normalizeStream(options.stream);\n  const tail = parseLimit(options.tail, \"tail\");\n  const logs = await readBackgroundTestRunLogs(pmRoot, runId, stream, tail);\n  return {\n    run: logs.run,\n    stream: logs.stream,\n    tail: logs.tail,\n    stdout: logs.stdout,\n    stderr: logs.stderr,\n  };\n}\n\nexport interface TestRunsStopCommandOptions {\n  force?: boolean;\n}\n\nexport async function runTestRunsStop(\n  runId: string,\n  options: TestRunsStopCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  run: unknown;\n  signal_sent: \"SIGTERM\" | \"SIGKILL\" | \"none\";\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const stopped = await stopBackgroundTestRun(pmRoot, runId, options.force === true);\n  return {\n    run: stopped.run,\n    signal_sent: stopped.signal_sent,\n  };\n}\n\nexport interface TestRunsResumeCommandOptions {\n  author?: string;\n  noExtensions?: boolean;\n}\n\nexport async function runTestRunsResume(\n  runId: string,\n  options: TestRunsResumeCommandOptions,\n  global: GlobalOptions,\n): Promise<{\n  resumed_from: string;\n  run: unknown;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const settings = await readSettings(pmRoot);\n  const requestedBy = resolveRequestedBy(options.author, settings.author_default);\n  const resumed = await resumeBackgroundTestRun(pmRoot, runId, requestedBy, options.noExtensions === true);\n  return {\n    resumed_from: runId,\n    run: resumed,\n  };\n}\n\nexport async function runTestRunsWorker(runId: string, global: GlobalOptions): Promise<{\n  id: string;\n  status: BackgroundTestRunStatus;\n  exit_code?: number;\n}> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  await ensureInitialized(pmRoot);\n  const finished = await runBackgroundTestRunWorker(pmRoot, runId, global.noExtensions === true);\n  return {\n    id: finished.id,\n    status: finished.status,\n    exit_code: finished.exit_code,\n  };\n}\n"]}

package/dist/cli/error-guidance.d.ts

@@ -20,14 +20,27 @@ export interface JsonErrorEnvelope {
     examples?: string[];
     next_steps?: string[];
 }
+export interface ErrorClassification {
+    type: string;
+    code: string;
+    title: string;
+    detail: string;
+    required: string;
+    why?: string;
+    examples?: string[];
+    next_steps?: string[];
+}
 export interface CommanderGuidanceContext {
     unknownCommandExamples?: string[];
     unknownCommandNextSteps?: string[];
 }
 export declare function renderGuidanceMessage(message: GuidanceMessage): string;
 export declare function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string;
+export declare function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification;
 export declare function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope;
 export declare function formatCommanderErrorForDisplay(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): string;
+export declare function classifyCommanderError(rawMessage: string, commandName: string | undefined, allowedTypes: string, context?: CommanderGuidanceContext): ErrorClassification;
 export declare function formatCommanderErrorForJson(rawMessage: string, commandName: string | undefined, allowedTypes: string, exitCode: number, context?: CommanderGuidanceContext): JsonErrorEnvelope;
 export declare function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope;
+export declare function classifyUnknownError(rawMessage: string): ErrorClassification;
 export {};

package/dist/cli/error-guidance.js

@@ -57,6 +57,25 @@ function guidanceToJsonEnvelope(message, exitCode) {
     }
     return payload;
 }
+function guidanceToClassification(message) {
+    const payload = {
+        type: message.type,
+        code: message.code,
+        title: message.title,
+        detail: message.happened,
+        required: message.required,
+    };
+    if (message.why) {
+        payload.why = message.why;
+    }
+    if (message.examples && message.examples.length > 0) {
+        payload.examples = message.examples;
+    }
+    if (message.nextSteps && message.nextSteps.length > 0) {
+        payload.next_steps = message.nextSteps;
+    }
+    return payload;
+}
 function normalizeMessage(message) {
     return message.replace(/\(outputHelp\)/g, "").trim();
 }
@@ -203,9 +222,17 @@ function buildPmCliErrorGuidance(rawMessage, context) {
             code: "no_update_fields",
             title: "No update fields supplied",
             happened: "The update command was called without any field-changing flags.",
-            required: "Provide at least one update field such as --status, --priority, --title, --tags, or --message.",
+            required: "Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.",
             why: "pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.",
-            examples: ['pm update pm-a1b2 --status in_progress --message "Start implementation"'],
+            examples: [
+                'pm update pm-a1b2 --status in_progress --message "Start implementation"',
+                'pm update pm-a1b2 --description "Clarified implementation scope" --message "Clarify task intent"',
+                'pm append pm-a1b2 --body "Detailed progress notes" --message "Append progress notes"',
+            ],
+            nextSteps: [
+                "Choose the item field you intend to change, then pair that change with --message for history context.",
+                "Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context.",
+            ],
         }), rawMessage, context);
     }
     if (message.startsWith("Invalid ") || message.includes(" must be ")) {
@@ -325,17 +352,27 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
 export function formatPmCliErrorForDisplay(rawMessage, context) {
     return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));
 }
+export function classifyPmCliError(rawMessage, context) {
+    return guidanceToClassification(buildPmCliErrorGuidance(rawMessage, context));
+}
 export function formatPmCliErrorForJson(rawMessage, exitCode, context) {
     return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);
 }
 export function formatCommanderErrorForDisplay(rawMessage, commandName, allowedTypes, context) {
     return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));
 }
+export function classifyCommanderError(rawMessage, commandName, allowedTypes, context) {
+    return guidanceToClassification(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));
+}
 export function formatCommanderErrorForJson(rawMessage, commandName, allowedTypes, exitCode, context) {
     return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);
 }
 export function formatUnknownErrorForJson(rawMessage, exitCode) {
-    const guidance = makeGuidanceMessage({
+    const guidance = buildUnknownErrorGuidance(rawMessage);
+    return guidanceToJsonEnvelope(guidance, exitCode);
+}
+function buildUnknownErrorGuidance(rawMessage) {
+    return makeGuidanceMessage({
         code: "unknown_error",
         title: "Unhandled error",
         happened: normalizeMessage(rawMessage),
@@ -343,6 +380,8 @@ export function formatUnknownErrorForJson(rawMessage, exitCode) {
         why: "Unexpected runtime failures can occur from environment or extension-level issues.",
         examples: ["pm --help", "pm health --json"],
     });
-    return guidanceToJsonEnvelope(guidance, exitCode);
+}
+export function classifyUnknownError(rawMessage) {
+    return guidanceToClassification(buildUnknownErrorGuidance(rawMessage));
 }
 //# sourceMappingURL=error-guidance.js.map

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 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 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: \"Provide at least one update field such as --status, --priority, --title, --tags, or --message.\",\n        why: \"pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.\",\n        examples: ['pm update pm-a1b2 --status in_progress --message \"Start implementation\"'],\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 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 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 = 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  return guidanceToJsonEnvelope(guidance, exitCode);\n}\n"]}
+{"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"]}

package/dist/cli/extension-command-help.d.ts

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+import type { RegisteredExtensionCommandDefinition, RegisteredExtensionFlagDefinitions } from "../core/extensions/index.js";
+export interface ExtensionCommandArgumentHelpDescriptor {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description?: string;
+}
+export interface ExtensionCommandHelpDescriptor {
+    command: string;
+    action: string;
+    description?: string;
+    intent?: string;
+    examples: string[];
+    failure_hints: string[];
+    arguments: ExtensionCommandArgumentHelpDescriptor[];
+    flags: Array<Record<string, unknown>>;
+    source?: {
+        layer: "global" | "project";
+        name: string;
+    };
+}
+export interface HelpOptionSummary {
+    flags: string;
+    long: string | null;
+    short: string | null;
+    description: string;
+    takes_value: boolean;
+    value_required: boolean;
+    value_name: string | null;
+    variadic: boolean;
+    required: boolean;
+    aliases: string[];
+    alias_for: string | null;
+    default_value?: unknown;
+}
+export declare function normalizeExtensionCommandPath(commandPath: string): string;
+export declare function collectDynamicExtensionFlagHelpByCommand(registrations: RegisteredExtensionFlagDefinitions[]): Map<string, string>;
+export declare function collectExtensionCommandHelpDescriptors(commandHandlers: string[], commandDefinitions: RegisteredExtensionCommandDefinition[], flagRegistrations: RegisteredExtensionFlagDefinitions[]): Map<string, ExtensionCommandHelpDescriptor>;
+export declare function applyDynamicExtensionArguments(command: Command, descriptor: ExtensionCommandHelpDescriptor): void;
+export declare function applyDynamicExtensionOptions(command: Command, descriptor: ExtensionCommandHelpDescriptor): void;
+export declare function buildDynamicExtensionHelpOptionSummaries(descriptor: ExtensionCommandHelpDescriptor | undefined): HelpOptionSummary[];
+export declare function mergeHelpOptionSummaries(base: HelpOptionSummary[], extension: HelpOptionSummary[]): HelpOptionSummary[];
+export declare function buildDynamicExtensionCommandMetadataHelp(descriptor: ExtensionCommandHelpDescriptor): string | null;
+export declare function commandAliases(command: Command): string[];
+export declare function findDirectChildCommand(parent: Command, name: string): Command | null;
+export declare function findCommandByPath(root: Command, pathParts: string[]): Command | null;
+export declare function ensureCommandPath(root: Command, pathParts: string[]): Command | null;