@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}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]="8b0fbe09-2221-5b8e-8712-90a83df19306")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
@@ -20,6 +20,7 @@ import { nowIso } from "../core/shared/time.js";
 import { resolveGlobalPmRoot, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, writeSettings } from "../core/store/settings.js";
 import { quoteCommandArg, renderPmCommand } from "./command-line.js";
+import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { ensureTypeFolderScaffold } from "./schema.js";
 // Cohesive helper groups now live in ./extension/* sibling modules. They are
 // imported for the command wiring that stays here and re-exported below so
@@ -321,21 +322,21 @@ const buildUnknownLifecycleActionError = (target, options) => {
         return new PmCliError(`One action flag is required. Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}. Bare \`pm package\` and \`pm extension\` default to --explore.`, EXIT_CODE.USAGE);
     }
     const command = `pm ${noun} ${suggestion.flag}`;
-    return new PmCliError(`Unknown ${noun} lifecycle action "${target}". Did you mean "${suggestion.flag}"?`, EXIT_CODE.USAGE, {
-        code: "unknown_lifecycle_action",
-        required: `Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}.`,
-        examples: [command, `pm ${noun} --help`],
-        recovery: {
-            attempted_command: `pm ${noun} ${target}`,
-            suggested_retry: command,
-            fallback_candidates: [
-                {
-                    source: "lifecycle_action",
-                    command,
-                    reason: `nearest lifecycle action for "${target}"`,
-                },
-            ],
-        },
+    return createUnknownSubcommandError({
+        command_path: noun,
+        display_name: `${noun} lifecycle`,
+        token_kind: "action",
+        token: target,
+        allowed: Object.keys(IMPLICIT_EXTENSION_ACTIONS),
+        retry_command: command,
+        message_suffix: `. Did you mean "${suggestion.flag}"?`,
+        fallback_candidates: [
+            {
+                source: "lifecycle_action",
+                command,
+                reason: `nearest lifecycle action for "${target}"`,
+            },
+        ],
     });
 };
 // Maps each boolean action flag to the lifecycle action it selects. `scaffold`
@@ -2190,4 +2191,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2
+//# debugId=8b0fbe09-2221-5b8e-8712-90a83df19306

package/dist/sdk/files.d.ts

@@ -1,6 +1,7 @@
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemDocument, LinkedFile, LinkScope } from "../types/index.js";
 import { type LinkedPathValidation } from "./linked-artifacts.js";
+import { type SourceLineRange, type SourceTraceabilityExplanation, type SourceTraceabilityReceipt } from "./traceability/source-traceability.js";
 /** Documents the files command options payload exchanged by command, SDK, and package integrations. */
 export interface FilesCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -112,6 +113,12 @@ export interface FilesLookupOptions {
     noTruncate?: boolean;
     /** Fail when any authoritative item cannot be read. */
     strictRead?: boolean;
+    /** Include rationale, governing-decision paths, and ambiguity receipts. */
+    explain?: boolean;
+    /** Optional inclusive line range; implies explain and requires one path. */
+    lineRange?: SourceLineRange;
+    /** Maximum relationship depth searched for a governing decision. */
+    decisionDepth?: number;
 }
 /** Token-efficient item identity returned by reverse linked-file lookup. */
 export interface FilesLookupItem {
@@ -134,6 +141,8 @@ export interface FilesLookupMatch {
     item: FilesLookupItem;
     /** Matching linked-file evidence. */
     files: LinkedFile[];
+    /** Optional bounded rationale and line-attribution explanation. */
+    traceability?: SourceTraceabilityExplanation;
 }
 /** Reverse linked-file lookup result with bounded output and read provenance. */
 export interface FilesLookupResult {
@@ -160,6 +169,8 @@ export interface FilesLookupResult {
     warnings: string[];
     /** Ordered reverse-traceability matches. */
     matches: FilesLookupMatch[];
+    /** Aggregate receipt for an explained source query. */
+    traceability_receipt?: SourceTraceabilityReceipt;
 }
 interface TextReference {
     field: string;

package/dist/sdk/files.js

@@ -4,7 +4,7 @@
  * Implements the pm files command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d")}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]="515cd35c-8e0e-51d4-8ad9-1cea5be8a572")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../core/fs/fs-utils.js";
@@ -20,6 +20,7 @@ import { readSettings } from "../core/store/settings.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { isPathWithinDirectory } from "../core/fs/path-utils.js";
 import { dedupeLinkedArtifacts, normalizeLinkedPath, renameArtifactsResultKey, runLinkedArtifacts, sortLinkedArtifacts, } from "./linked-artifacts.js";
+import { explainSourceTraceability, } from "./traceability/source-traceability.js";
 /** Bounds fuzzy relative-path scanning while preserving full absolute-path discovery. */
 const RELATIVE_REFERENCE_SCAN_MAX_CHARS = 32_768;
 function normalizeCandidatePathForOutput(value) {
@@ -251,8 +252,51 @@ function projectFilesLookupItem(item) {
         updated_at: item.updated_at,
     };
 }
+function compareFilesLookupCandidates(left, right) {
+    const byPriority = left.item.priority - right.item.priority;
+    if (byPriority !== 0)
+        return byPriority;
+    const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
+    return byUpdated === 0
+        ? left.item.id.localeCompare(right.item.id)
+        : byUpdated;
+}
+function matchingFilesLookupCandidates(params) {
+    return params.metadata
+        .map((item) => ({
+        item,
+        files: (item.files ?? [])
+            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
+            (params.scope === undefined || file.scope === params.scope))
+            .sort((left, right) => {
+            const byPath = left.path.localeCompare(right.path);
+            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
+        }),
+    }))
+        .filter((match) => match.files.length > 0)
+        .sort(compareFilesLookupCandidates);
+}
+async function resolveFilesLookupTraceability(params) {
+    if (!params.explain)
+        return undefined;
+    return explainSourceTraceability({
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        candidates: params.matching,
+        corpus: params.metadata,
+        ...(params.lineRange ? { lineRange: params.lineRange } : {}),
+        ...(params.decisionDepth === undefined
+            ? {}
+            : { decisionDepth: params.decisionDepth }),
+    });
+}
 async function queryFilesLookupIndex(params) {
-    if ([params.strictRead, params.noTruncate, hasActiveOnReadHooks()].includes(true)) {
+    if ([
+        params.strictRead,
+        params.noTruncate,
+        params.explain,
+        hasActiveOnReadHooks(),
+    ].includes(true)) {
         return null;
     }
     const indexState = await readItemMetadataDerivedIndexState(params.pmRoot, [
@@ -272,32 +316,34 @@ async function queryFilesLookupIndex(params) {
 async function queryFilesLookupSource(params) {
     const warnings = [];
     const metadata = await listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, warnings, params.settings.schema);
-    const matching = metadata
-        .map((item) => ({
-        item,
-        files: (item.files ?? [])
-            .filter((file) => params.paths.includes(normalizeLinkedPath(file.path)) &&
-            (params.scope === undefined || file.scope === params.scope))
-            .sort((left, right) => {
-            const byPath = left.path.localeCompare(right.path);
-            return byPath === 0 ? left.scope.localeCompare(right.scope) : byPath;
-        }),
-    }))
-        .filter((match) => match.files.length > 0)
-        .sort((left, right) => {
-        const byPriority = left.item.priority - right.item.priority;
-        if (byPriority !== 0)
-            return byPriority;
-        const byUpdated = right.item.updated_at.localeCompare(left.item.updated_at);
-        return byUpdated === 0
-            ? left.item.id.localeCompare(right.item.id)
-            : byUpdated;
+    const matching = matchingFilesLookupCandidates({
+        metadata,
+        paths: params.paths,
+        scope: params.scope,
     });
     const readWarnings = warnings.filter((warning) => /^item_list_(?:item|directory)_read_failed:/u.test(warning));
     if (params.strictRead && readWarnings.length > 0) {
         throw new PmCliError(`Files lookup could not read every item: ${readWarnings.join("; ")}`, EXIT_CODE.GENERIC_FAILURE);
     }
-    const page = matching.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
+    const traceability = await resolveFilesLookupTraceability({
+        explain: params.explain,
+        workspaceRoot: params.workspaceRoot,
+        paths: params.paths,
+        matching,
+        metadata,
+        lineRange: params.lineRange,
+        decisionDepth: params.decisionDepth,
+    });
+    const ranked = traceability
+        ? [...matching].sort((left, right) => {
+            const byScore = traceability.explanations.get(right.item.id).score -
+                traceability.explanations.get(left.item.id).score;
+            if (byScore !== 0)
+                return byScore;
+            return compareFilesLookupCandidates(left, right);
+        })
+        : matching;
+    const page = ranked.slice(params.offset, params.limit === undefined ? undefined : params.offset + params.limit);
     return {
         paths: params.paths,
         total: matching.length,
@@ -314,7 +360,11 @@ async function queryFilesLookupSource(params) {
         matches: page.map((match) => ({
             item: projectFilesLookupItem(match.item),
             files: match.files,
+            ...(traceability
+                ? { traceability: traceability.explanations.get(match.item.id) }
+                : {}),
         })),
+        ...(traceability ? { traceability_receipt: traceability.receipt } : {}),
     };
 }
 /** Resolve the pm items that reference one or more source paths. */
@@ -325,6 +375,9 @@ export async function runFilesLookup(options, global) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const paths = await normalizeFilesLookupPaths(options.paths, workspaceRoot);
+    if (options.lineRange && paths.length !== 1) {
+        throw new PmCliError("Files lookup line attribution requires exactly one source path.", EXIT_CODE.USAGE);
+    }
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const { offset, limit } = resolveFilesLookupWindow(options);
@@ -337,6 +390,7 @@ export async function runFilesLookup(options, global) {
         offset,
         strictRead: options.strictRead === true,
         noTruncate: options.noTruncate === true,
+        explain: options.explain === true || options.lineRange !== undefined,
     });
     if (indexed) {
         return {
@@ -364,6 +418,10 @@ export async function runFilesLookup(options, global) {
         limit,
         offset,
         strictRead: options.strictRead === true,
+        workspaceRoot,
+        explain: options.explain === true || options.lineRange !== undefined,
+        lineRange: options.lineRange,
+        decisionDepth: options.decisionDepth,
     });
 }
 /** Implements run files discover for the public runtime surface of this module. */
@@ -479,4 +537,4 @@ export async function runFilesDiscover(id, options, global) {
     };
 }
 //# sourceMappingURL=files.js.map
-//# debugId=5e45d0f1-a1a7-50ea-a9a3-ec6283d3471d
+//# debugId=515cd35c-8e0e-51d4-8ad9-1cea5be8a572

package/dist/sdk/generated/generated-error-code-catalog-part-1.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module sdk/generated-error-code-catalog-part-1
+ *
+ * Generated by scripts/generate-error-code-catalog.mjs. Do not edit manually.
+ */
+import type { PmErrorCodeContract } from "../error-code-catalog.js";
+/** Generated partition 1 of the exhaustive error-code catalog. */
+export declare const PM_ERROR_CODE_CATALOG_PART_1: PmErrorCodeContract[];