@unbrained/pm-cli 2026.5.30 → 2026.6.5

package/dist/cli/commands/validate.d.ts

@@ -15,6 +15,7 @@ export interface ValidateCommandOptions {
     checkCommandReferences?: boolean;
     scanMode?: string;
     metadataProfile?: string;
+    fixHints?: boolean;
 }
 export interface ValidateCheck {
     name: ValidateCheckName;

package/dist/cli/commands/validate.js

@@ -1,10 +1,11 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="07339f90-f764-5ffb-b4c7-f0bf9a410f89")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="776e2ca9-52d6-5274-9230-4d9b961456e5")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
+import { buildRemediationCommands } from "../../core/diagnostics/remediation.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { scanHistoryDrift } from "../../core/history/drift-scan.js";
@@ -109,7 +110,7 @@ const METADATA_TRUNCATED_KEY_BY_FIELD = {
 };
 const GIT_LS_FILES_MAX_BUFFER = 32 * 1024 * 1024;
 const FILE_LIST_SUMMARY_LIMIT = 40;
-const DIAGNOSTIC_LIST_SUMMARY_LIMIT = 40;
+const DIAGNOSTIC_LIST_SUMMARY_LIMIT = 5;
 const execFileAsync = promisify(execFile);
 function normalizeRelativePath(value) {
     return value.replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/^\/+/, "");
@@ -488,6 +489,36 @@ function buildResolutionRemediationCommand(row) {
         .join(" ");
     return `pm update ${row.id} ${fieldArguments} --message \"Backfill resolution metadata\"`;
 }
+/**
+ * Attach a uniform, machine-executable `fix_hints` array to a validate check's
+ * details when `--fix-hints` is requested. The resolution check's existing
+ * per-row remediation commands (which already carry concrete item ids) are
+ * aliased in so agents read one uniform field across every check; all other
+ * checks derive one generic command per distinct warning code from the shared
+ * remediation registry. Generic hints may contain `<id>`/`<field>`/`<path>`
+ * placeholders the caller substitutes before running — they are templates, not
+ * always directly executable as-is. Read-only: this only enriches the diagnostic
+ * output, never mutates any item.
+ */
+function attachValidateFixHints(check, checkWarnings) {
+    const existingResolutionHints = check.details?.missing_resolution_remediation_hints;
+    const aliasedResolution = Array.isArray(existingResolutionHints) && existingResolutionHints.length > 0;
+    const fixHints = aliasedResolution
+        ? existingResolutionHints.filter((hint) => typeof hint === "string")
+        : buildRemediationCommands(checkWarnings);
+    if (fixHints.length === 0) {
+        return;
+    }
+    // The resolution check truncates its per-row hint list for low-token output;
+    // carry that marker onto fix_hints so an agent knows the list is partial and
+    // there are more items to repair beyond the ones shown.
+    const truncated = aliasedResolution && check.details?.missing_resolution_remediation_hints_truncated === true;
+    check.details = {
+        ...check.details,
+        fix_hints: fixHints,
+        ...(truncated ? { fix_hints_truncated: true } : {}),
+    };
+}
 function resolveRequestedChecks(options) {
     const requested = new Set();
     if (options.checkMetadata) {
@@ -745,7 +776,7 @@ function detectLifecycleDependencyCycles(activeItems) {
         cycle_sample_paths: cycleSamplePaths,
     };
 }
-function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy) {
+function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy, verboseDiagnostics) {
     const itemsById = new Map(items.map((item) => [item.id, item]));
     const blockedStatuses = statusRegistry.blocked_statuses.size > 0 ? statusRegistry.blocked_statuses : new Set(["blocked"]);
     const activeItems = items.filter((item) => !isTerminalStatus(item.status, statusRegistry));
@@ -835,11 +866,12 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
             ? "validate_lifecycle_dependency_cycles_error"
             : "validate_lifecycle_dependency_cycles"}:${dependencyCycleDiagnostics.cycle_count}`);
     }
-    const summarizedClosureLikeRows = summarizeList(closureLikeRows.map((row) => `${row.id}:${row.fields.join(",")}`));
-    const summarizedTerminalParentRows = summarizeList(terminalParentRows.map((row) => `${row.id}:${row.parent_id}:${row.parent_status}`));
-    const summarizedStaleBlockerRows = summarizeList(staleBlockerRows.map((row) => `${row.id}:${row.status}:${row.reasons.join(",")}`));
-    const summarizedDependencyCycleItemIds = summarizeList(dependencyCycleDiagnostics.cycle_item_ids);
-    const summarizedDependencyCycleSamplePaths = summarizeList(dependencyCycleDiagnostics.cycle_sample_paths);
+    const diagnosticLimit = verboseDiagnostics ? Number.POSITIVE_INFINITY : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
+    const summarizedClosureLikeRows = summarizeList(closureLikeRows.map((row) => `${row.id}:${row.fields.join(",")}`), diagnosticLimit);
+    const summarizedTerminalParentRows = summarizeList(terminalParentRows.map((row) => `${row.id}:${row.parent_id}:${row.parent_status}`), diagnosticLimit);
+    const summarizedStaleBlockerRows = summarizeList(staleBlockerRows.map((row) => `${row.id}:${row.status}:${row.reasons.join(",")}`), diagnosticLimit);
+    const summarizedDependencyCycleItemIds = summarizeList(dependencyCycleDiagnostics.cycle_item_ids, diagnosticLimit);
+    const summarizedDependencyCycleSamplePaths = summarizeList(dependencyCycleDiagnostics.cycle_sample_paths, diagnosticLimit);
     return {
         check: {
             name: "lifecycle",
@@ -985,7 +1017,7 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
         warnings,
     };
 }
-async function buildHistoryDriftCheck(pmRoot, items) {
+async function buildHistoryDriftCheck(pmRoot, items, verboseDiagnostics) {
     const { missingStreams, unreadableStreams, hashMismatches, chainMismatches, driftedItems } = await scanHistoryDrift(pmRoot, items);
     const warnings = [];
     if (missingStreams.length > 0) {
@@ -1000,7 +1032,8 @@ async function buildHistoryDriftCheck(pmRoot, items) {
     if (chainMismatches.length > 0) {
         warnings.push(`validate_history_drift_chain_mismatches:${chainMismatches.length}`);
     }
-    const summarizedDrifted = summarizeList(driftedItems);
+    const diagnosticLimit = verboseDiagnostics ? Number.POSITIVE_INFINITY : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
+    const summarizedDrifted = summarizeList(driftedItems, diagnosticLimit);
     return {
         check: {
             name: "history_drift",
@@ -1026,7 +1059,7 @@ function summarizeCommandReferenceRow(ownerId, referencedId, command) {
     const commandPreview = normalizedCommand.length > 120 ? `${normalizedCommand.slice(0, 117)}...` : normalizedCommand;
     return `${ownerId}:${referencedId}:${commandPreview}`;
 }
-function buildCommandReferencesCheck(items, idPrefix) {
+function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
     const knownIds = new Set(items.map((item) => item.id.toLowerCase()));
     let linkedCommandsScanned = 0;
     let referencedPmIdCount = 0;
@@ -1056,9 +1089,10 @@ function buildCommandReferencesCheck(items, idPrefix) {
         .filter((value) => value.length > 0)
         .sort((left, right) => left.localeCompare(right));
     const warnings = uniqueStaleReferenceRows.length > 0 ? [`validate_command_references_stale_pm_ids:${uniqueStaleReferenceRows.length}`] : [];
-    const summarizedRows = summarizeList(uniqueStaleReferenceRows);
-    const summarizedStalePmIds = summarizeList(stalePmIds);
-    const summarizedReferencedPmIds = summarizeList([...referencedPmIds].sort((left, right) => left.localeCompare(right)));
+    const diagnosticLimit = verboseDiagnostics ? Number.POSITIVE_INFINITY : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
+    const summarizedRows = summarizeList(uniqueStaleReferenceRows, diagnosticLimit);
+    const summarizedStalePmIds = summarizeList(stalePmIds, diagnosticLimit);
+    const summarizedReferencedPmIds = summarizeList([...referencedPmIds].sort((left, right) => left.localeCompare(right)), diagnosticLimit);
     return {
         check: {
             name: "command_references",
@@ -1101,35 +1135,31 @@ export async function runValidate(options, global) {
     const workspaceRoot = resolveWorkspaceRoot(pmRoot);
     const checks = [];
     const warnings = [...new Set(itemReadWarnings)];
+    const fixHintsEnabled = options.fixHints === true;
+    const record = (built) => {
+        if (fixHintsEnabled) {
+            attachValidateFixHints(built.check, built.warnings);
+        }
+        checks.push(built.check);
+        warnings.push(...built.warnings);
+    };
     if (requestedChecks.has("metadata")) {
-        const metadataCheck = buildMetadataCheck(items, metadataPolicy, statusRegistry, Boolean(options.verboseDiagnostics));
-        checks.push(metadataCheck.check);
-        warnings.push(...metadataCheck.warnings);
+        record(buildMetadataCheck(items, metadataPolicy, statusRegistry, Boolean(options.verboseDiagnostics)));
     }
     if (requestedChecks.has("resolution")) {
-        const resolutionCheck = buildResolutionCheck(items, statusRegistry, Boolean(options.verboseDiagnostics));
-        checks.push(resolutionCheck.check);
-        warnings.push(...resolutionCheck.warnings);
+        record(buildResolutionCheck(items, statusRegistry, Boolean(options.verboseDiagnostics)));
     }
     if (requestedChecks.has("lifecycle")) {
-        const lifecycleCheck = buildLifecycleCheck(items, Boolean(options.checkStaleBlockers), dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy);
-        checks.push(lifecycleCheck.check);
-        warnings.push(...lifecycleCheck.warnings);
+        record(buildLifecycleCheck(items, Boolean(options.checkStaleBlockers), dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy, Boolean(options.verboseDiagnostics)));
     }
     if (requestedChecks.has("files")) {
-        const filesCheck = await buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, Boolean(options.includePmInternals), Boolean(options.verboseFileLists));
-        checks.push(filesCheck.check);
-        warnings.push(...filesCheck.warnings);
+        record(await buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, Boolean(options.includePmInternals), Boolean(options.verboseFileLists)));
     }
     if (requestedChecks.has("command_references")) {
-        const commandReferencesCheck = buildCommandReferencesCheck(items, settings.id_prefix);
-        checks.push(commandReferencesCheck.check);
-        warnings.push(...commandReferencesCheck.warnings);
+        record(buildCommandReferencesCheck(items, settings.id_prefix, Boolean(options.verboseDiagnostics)));
     }
     if (requestedChecks.has("history_drift")) {
-        const historyDriftCheck = await buildHistoryDriftCheck(pmRoot, items);
-        checks.push(historyDriftCheck.check);
-        warnings.push(...historyDriftCheck.warnings);
+        record(await buildHistoryDriftCheck(pmRoot, items, Boolean(options.verboseDiagnostics)));
     }
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const hasErrors = checks.some((check) => check.status === "error");
@@ -1142,4 +1172,4 @@ export async function runValidate(options, global) {
     };
 }
 //# sourceMappingURL=validate.js.map
-//# debugId=07339f90-f764-5ffb-b4c7-f0bf9a410f89
+//# debugId=776e2ca9-52d6-5274-9230-4d9b961456e5