@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/error-code-catalog.js

@@ -1,154 +1,2 @@
-/**
- * @module sdk/error-code-catalog
- *
- * Defines the stable, discoverable error vocabulary used across CLI, SDK, MCP,
- * packages, and generated contract surfaces.
- */
-/** Stable shell exit-code taxonomy shared by every structured error. */
-
-!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]="c76fa303-6672-5c1e-9cf5-3a08bd3a7814")}catch(e){}}();
-export const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS = [
-    { exit_code: 1, class: "generic_failure" },
-    { exit_code: 2, class: "usage" },
-    { exit_code: 3, class: "not_found" },
-    { exit_code: 4, class: "conflict" },
-    { exit_code: 5, class: "dependency_failed" },
-];
-const ERROR_CLASS_BY_EXIT_CODE = new Map(PM_ERROR_CODE_EXIT_CLASS_CONTRACTS.map((contract) => [contract.exit_code, contract.class]));
-/** Normalize a declared non-empty string set into stable contract order. */
-function normalizeContractList(values) {
-    return [
-        ...new Set(values.map((value) => value.trim()).filter(Boolean)),
-    ].sort();
-}
-function normalizeOwnedStates(states) {
-    if (!states)
-        return [];
-    const seenStates = new Set();
-    const seenProbes = new Set();
-    return states
-        .map((state) => {
-        const normalizedState = state.state.trim();
-        const probeId = state.probe_id.trim();
-        const entrypoints = normalizeContractList(state.entrypoints);
-        if (!/^[a-z][a-z0-9_]*$/.test(normalizedState) ||
-            !/^[a-z][a-z0-9-]*$/.test(probeId) ||
-            entrypoints.length === 0 ||
-            seenStates.has(normalizedState) ||
-            seenProbes.has(probeId)) {
-            throw new TypeError("Invalid pm refusal state contract");
-        }
-        seenStates.add(normalizedState);
-        seenProbes.add(probeId);
-        return {
-            state: normalizedState,
-            probe_id: probeId,
-            entrypoints,
-            expected_exit_class: state.expected_exit_class,
-        };
-    })
-        .sort((left, right) => left.state.localeCompare(right.state));
-}
-function isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases) {
-    return ![
-        [1, 2, 3, 4, 5].includes(declaration.exit_code),
-        declaration.meaning.trim().length > 0,
-        declaration.recovery.trim().length > 0,
-        sources.length > 0,
-        emittingCommands.length > 0,
-        /^[a-z][a-z0-9_]*$/.test(canonicalCode),
-        aliases.every((alias) => /^[a-z][a-z0-9_]*$/.test(alias)),
-        ERROR_CLASS_BY_EXIT_CODE.get(declaration.exit_code) === declaration.class,
-    ].includes(false);
-}
-function resolveCanonicalErrorCodeDeclaration(declaration, byCode) {
-    let current = declaration;
-    const path = new Set();
-    while (current.canonical_code !== current.code) {
-        if (path.has(current.code)) {
-            throw new TypeError(`Alias cycle in pm error code catalog: ${declaration.code}`);
-        }
-        path.add(current.code);
-        const target = byCode.get(current.canonical_code);
-        if (!target) {
-            throw new TypeError(`Invalid pm error code contract: ${declaration.code}`);
-        }
-        current = target;
-    }
-    return current;
-}
-function validateErrorCodeAliases(declarations) {
-    const byCode = new Map(declarations.map((entry) => [entry.code, entry]));
-    for (const declaration of declarations) {
-        const canonical = resolveCanonicalErrorCodeDeclaration(declaration, byCode);
-        if (canonical.exit_code !== declaration.exit_code ||
-            canonical.class !== declaration.class) {
-            throw new TypeError(`Alias transport mismatch for pm error code: ${declaration.code}`);
-        }
-        const expectedAliases = declarations
-            .filter((candidate) => candidate.code !== canonical.code &&
-            candidate.canonical_code === canonical.code)
-            .map((candidate) => candidate.code)
-            .sort();
-        if (declaration.code === canonical.code
-            ? JSON.stringify(declaration.aliases) !==
-                JSON.stringify(expectedAliases)
-            : declaration.aliases.length > 0) {
-            throw new TypeError(`Invalid pm error code contract: ${declaration.code}`);
-        }
-    }
-}
-/** Validate, normalize, sort, and freeze an error-code catalog. */
-export function definePmErrorCodeCatalog(declarations) {
-    const seen = new Set();
-    const normalized = declarations.map((declaration) => {
-        const code = declaration.code.trim();
-        if (!/^[a-z][a-z0-9_]*$/.test(code)) {
-            throw new TypeError(`Invalid pm error code: ${JSON.stringify(declaration.code)}`);
-        }
-        if (seen.has(code)) {
-            throw new TypeError(`Duplicate pm error code: ${code}`);
-        }
-        seen.add(code);
-        const sources = normalizeContractList(declaration.sources);
-        const emittingCommands = normalizeContractList(declaration.emitting_commands);
-        const canonicalCode = (declaration.canonical_code ?? code).trim();
-        const aliases = normalizeContractList(declaration.aliases ?? []);
-        const ownedStates = normalizeOwnedStates(declaration.owned_states);
-        if (!isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases)) {
-            throw new TypeError(`Invalid pm error code contract: ${code}`);
-        }
-        if (ownedStates.some((state) => state.expected_exit_class !== declaration.class)) {
-            throw new TypeError(`Invalid pm refusal state exit class: ${code}`);
-        }
-        return Object.freeze({
-            ...declaration,
-            code,
-            meaning: declaration.meaning.trim(),
-            recovery: declaration.recovery.trim(),
-            sources,
-            emitting_commands: emittingCommands,
-            canonical_code: canonicalCode,
-            aliases,
-            owned_states: ownedStates,
-        });
-    });
-    validateErrorCodeAliases(normalized);
-    return Object.freeze(normalized.sort((left, right) => left.code.localeCompare(right.code)));
-}
-/** Resolve an emitted code through its stable compatibility alias group. */
-export function resolveCanonicalPmErrorCodeContract(code, catalog) {
-    const emitted = resolvePmErrorCodeContract(code, catalog);
-    return resolvePmErrorCodeContract(emitted.canonical_code ?? emitted.code, catalog);
-}
-/** Resolve one declared error contract and fail closed for unknown vocabulary. */
-export function resolvePmErrorCodeContract(code, catalog) {
-    const normalized = code.trim();
-    const contract = catalog.find((entry) => entry.code === normalized);
-    if (!contract) {
-        throw new TypeError(`Unknown pm error code "${normalized}"`);
-    }
-    return contract;
-}
+!(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]="a2e77c4f-3899-518a-885f-ce5dd2090ac6")}catch(e2){}})();const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS=[{exit_code:1,class:"generic_failure"},{exit_code:2,class:"usage"},{exit_code:3,class:"not_found"},{exit_code:4,class:"conflict"},{exit_code:5,class:"dependency_failed"}];const ERROR_CLASS_BY_EXIT_CODE=new Map(PM_ERROR_CODE_EXIT_CLASS_CONTRACTS.map(contract=>[contract.exit_code,contract.class]));function normalizeContractList(values){return[...new Set(values.map(value=>value.trim()).filter(Boolean))].sort()}function normalizeOwnedStates(states){if(!states)return[];const seenStates=new Set;const seenProbes=new Set;return states.map(state=>{const normalizedState=state.state.trim();const probeId=state.probe_id.trim();const entrypoints=normalizeContractList(state.entrypoints);if(!/^[a-z][a-z0-9_]*$/.test(normalizedState)||!/^[a-z][a-z0-9-]*$/.test(probeId)||entrypoints.length===0||seenStates.has(normalizedState)||seenProbes.has(probeId)){throw new TypeError("Invalid pm refusal state contract")}seenStates.add(normalizedState);seenProbes.add(probeId);return{state:normalizedState,probe_id:probeId,entrypoints,expected_exit_class:state.expected_exit_class}}).sort((left,right)=>left.state.localeCompare(right.state))}function isValidNormalizedErrorCodeContract(declaration,sources,emittingCommands,canonicalCode,aliases){return![[1,2,3,4,5].includes(declaration.exit_code),declaration.meaning.trim().length>0,declaration.recovery.trim().length>0,sources.length>0,emittingCommands.length>0,/^[a-z][a-z0-9_]*$/.test(canonicalCode),aliases.every(alias=>/^[a-z][a-z0-9_]*$/.test(alias)),ERROR_CLASS_BY_EXIT_CODE.get(declaration.exit_code)===declaration.class].includes(false)}function resolveCanonicalErrorCodeDeclaration(declaration,byCode){let current=declaration;const path=new Set;while(current.canonical_code!==current.code){if(path.has(current.code)){throw new TypeError(`Alias cycle in pm error code catalog: ${declaration.code}`)}path.add(current.code);const target=byCode.get(current.canonical_code);if(!target){throw new TypeError(`Invalid pm error code contract: ${declaration.code}`)}current=target}return current}function validateErrorCodeAliases(declarations){const byCode=new Map(declarations.map(entry=>[entry.code,entry]));for(const declaration of declarations){const canonical=resolveCanonicalErrorCodeDeclaration(declaration,byCode);if(canonical.exit_code!==declaration.exit_code||canonical.class!==declaration.class){throw new TypeError(`Alias transport mismatch for pm error code: ${declaration.code}`)}const expectedAliases=declarations.filter(candidate=>candidate.code!==canonical.code&&candidate.canonical_code===canonical.code).map(candidate=>candidate.code).sort();if(declaration.code===canonical.code?JSON.stringify(declaration.aliases)!==JSON.stringify(expectedAliases):declaration.aliases.length>0){throw new TypeError(`Invalid pm error code contract: ${declaration.code}`)}}}function definePmErrorCodeCatalog(declarations){const seen=new Set;const normalized=declarations.map(declaration=>{const code=declaration.code.trim();if(!/^[a-z][a-z0-9_]*$/.test(code)){throw new TypeError(`Invalid pm error code: ${JSON.stringify(declaration.code)}`)}if(seen.has(code)){throw new TypeError(`Duplicate pm error code: ${code}`)}seen.add(code);const sources=normalizeContractList(declaration.sources);const emittingCommands=normalizeContractList(declaration.emitting_commands);const canonicalCode=(declaration.canonical_code??code).trim();const aliases=normalizeContractList(declaration.aliases??[]);const ownedStates=normalizeOwnedStates(declaration.owned_states);if(!isValidNormalizedErrorCodeContract(declaration,sources,emittingCommands,canonicalCode,aliases)){throw new TypeError(`Invalid pm error code contract: ${code}`)}if(ownedStates.some(state=>state.expected_exit_class!==declaration.class)){throw new TypeError(`Invalid pm refusal state exit class: ${code}`)}return Object.freeze({...declaration,code,meaning:declaration.meaning.trim(),recovery:declaration.recovery.trim(),sources,emitting_commands:emittingCommands,canonical_code:canonicalCode,aliases,owned_states:ownedStates})});validateErrorCodeAliases(normalized);return Object.freeze(normalized.sort((left,right)=>left.code.localeCompare(right.code)))}function resolveCanonicalPmErrorCodeContract(code,catalog){const emitted=resolvePmErrorCodeContract(code,catalog);return resolvePmErrorCodeContract(emitted.canonical_code??emitted.code,catalog)}function resolvePmErrorCodeContract(code,catalog){const normalized=code.trim();const contract=catalog.find(entry=>entry.code===normalized);if(!contract){throw new TypeError(`Unknown pm error code "${normalized}"`)}return contract}export{PM_ERROR_CODE_EXIT_CLASS_CONTRACTS,definePmErrorCodeCatalog,resolveCanonicalPmErrorCodeContract,resolvePmErrorCodeContract};
 //# sourceMappingURL=error-code-catalog.js.map
-//# debugId=c76fa303-6672-5c1e-9cf5-3a08bd3a7814

package/dist/sdk/error-runtime.js

@@ -1,59 +1,2 @@
-/**
- * @module sdk/error-runtime
- *
- * Provides presentation-independent normalization for values thrown through CLI and SDK runtimes.
- */
-
-!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]="5810cf1d-fc9a-597b-a47e-a914009fadfa")}catch(e){}}();
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-/** Returns a stable message for errors and unknown thrown values. */
-export function describeUnknownError(error) {
-    if (error instanceof PmCliError) {
-        return error.message;
-    }
-    if (error instanceof Error) {
-        return error.message;
-    }
-    return "Unknown failure";
-}
-/** Reads a finite numeric exit code from an arbitrary thrown value. */
-export function readThrownExitCode(error) {
-    if (typeof error !== "object" || error === null || !("exitCode" in error)) {
-        return undefined;
-    }
-    const exitCode = error.exitCode;
-    return typeof exitCode === "number" && Number.isFinite(exitCode)
-        ? exitCode
-        : undefined;
-}
-/** Normalizes thrown exit codes to a positive integer failure status. */
-export function normalizeThrownExitCode(exitCode) {
-    const normalized = Math.trunc(exitCode);
-    return normalized > EXIT_CODE.SUCCESS
-        ? normalized
-        : EXIT_CODE.GENERIC_FAILURE;
-}
-/** Identifies errors emitted by Commander without importing its private classes. */
-export function isCommanderError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        typeof error.code === "string" &&
-        error.code.startsWith("commander."));
-}
-/** Converts non-Error thrown values into errors suitable for Sentry capture. */
-export function wrapThrownErrorForSentry(error, message) {
-    if (error instanceof Error) {
-        return error;
-    }
-    const wrapped = new Error(message);
-    const exitCode = readThrownExitCode(error);
-    /* c8 ignore next */
-    if (exitCode !== undefined) {
-        wrapped.exitCode = normalizeThrownExitCode(exitCode);
-    }
-    return wrapped;
-}
+!(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]="bdf3dec8-63d1-5ea6-a413-64be0ae8f69f")}catch(e2){}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";function describeUnknownError(error){if(error instanceof PmCliError){return error.message}if(error instanceof Error){return error.message}return"Unknown failure"}function readThrownExitCode(error){if(typeof error!=="object"||error===null||!("exitCode"in error)){return void 0}const exitCode=error.exitCode;return typeof exitCode==="number"&&Number.isFinite(exitCode)?exitCode:void 0}function normalizeThrownExitCode(exitCode){const normalized=Math.trunc(exitCode);return normalized>EXIT_CODE.SUCCESS?normalized:EXIT_CODE.GENERIC_FAILURE}function isCommanderError(error){return typeof error==="object"&&error!==null&&"code"in error&&typeof error.code==="string"&&error.code.startsWith("commander.")}function wrapThrownErrorForSentry(error,message){if(error instanceof Error){return error}const wrapped=new Error(message);const exitCode=readThrownExitCode(error);if(exitCode!==void 0){wrapped.exitCode=normalizeThrownExitCode(exitCode)}return wrapped}export{describeUnknownError,isCommanderError,normalizeThrownExitCode,readThrownExitCode,wrapThrownErrorForSentry};
 //# sourceMappingURL=error-runtime.js.map
-//# debugId=5810cf1d-fc9a-597b-a47e-a914009fadfa

package/dist/sdk/errors.js

@@ -1,59 +1,2 @@
-/**
- * @module sdk/errors
- *
- * Defines public SDK APIs and package-author helpers for Errors.
- */
-
-!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]="41012e87-ed61-56b2-8505-8f786b3952b2")}catch(e){}}();
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-/**
- * The `Error.name` value carried by every {@link PmCliExpectedError}. The CLI's
- * top-level handler and the Sentry crash filter recognise expected errors by
- * matching this exact string rather than by `instanceof`, so an error thrown
- * from a separately bundled or linked extension is still treated as expected.
- */
-export const PM_CLI_EXPECTED_ERROR_NAME = "PmCliError";
-function normalizeExpectedErrorExitCode(value) {
-    if (!Number.isFinite(value)) {
-        throw new TypeError("createPmCliExpectedError options.exitCode must be a finite number");
-    }
-    const normalized = Math.trunc(value);
-    if (normalized <= EXIT_CODE.SUCCESS) {
-        throw new TypeError("createPmCliExpectedError options.exitCode must be a positive exit code");
-    }
-    return normalized;
-}
-/**
- * Create a package-safe expected CLI error.
- *
- * The CLI and Sentry filtering rely on the public error shape rather than a
- * shared class identity, so package authors can throw this from bundled,
- * linked, or separately installed extension code.
- */
-export function createPmCliExpectedError(message, options = {}) {
-    if (typeof message !== "string" || message.trim().length === 0) {
-        throw new TypeError("createPmCliExpectedError message must be a non-empty string");
-    }
-    const error = new PmCliError(message, normalizeExpectedErrorExitCode(options.exitCode ?? EXIT_CODE.USAGE), options.context ?? {});
-    if ("cause" in options) {
-        Object.defineProperty(error, "cause", {
-            value: options.cause,
-            enumerable: false,
-            configurable: true,
-            writable: true,
-        });
-    }
-    return error;
-}
-/** Implements check whether pm cli expected error for the public runtime surface of this module. */
-export function isPmCliExpectedError(error) {
-    if (!(error instanceof Error) || error.name !== PM_CLI_EXPECTED_ERROR_NAME) {
-        return false;
-    }
-    const candidate = error;
-    return (typeof candidate.exitCode === "number" &&
-        Number.isFinite(candidate.exitCode));
-}
+!(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]="9133d39d-b2fb-5f99-8fd3-87a7d2f8df6d")}catch(e2){}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_CLI_EXPECTED_ERROR_NAME="PmCliError";function normalizeExpectedErrorExitCode(value){if(!Number.isFinite(value)){throw new TypeError("createPmCliExpectedError options.exitCode must be a finite number")}const normalized=Math.trunc(value);if(normalized<=EXIT_CODE.SUCCESS){throw new TypeError("createPmCliExpectedError options.exitCode must be a positive exit code")}return normalized}function createPmCliExpectedError(message,options={}){if(typeof message!=="string"||message.trim().length===0){throw new TypeError("createPmCliExpectedError message must be a non-empty string")}const error=new PmCliError(message,normalizeExpectedErrorExitCode(options.exitCode??EXIT_CODE.USAGE),options.context??{});if("cause"in options){Object.defineProperty(error,"cause",{value:options.cause,enumerable:false,configurable:true,writable:true})}return error}function isPmCliExpectedError(error){if(!(error instanceof Error)||error.name!==PM_CLI_EXPECTED_ERROR_NAME){return false}const candidate=error;return typeof candidate.exitCode==="number"&&Number.isFinite(candidate.exitCode)}export{PM_CLI_EXPECTED_ERROR_NAME,createPmCliExpectedError,isPmCliExpectedError};
 //# sourceMappingURL=errors.js.map
-//# debugId=41012e87-ed61-56b2-8505-8f786b3952b2

package/dist/sdk/eval.js

@@ -1,191 +1,2 @@
-/**
- * @module sdk/eval
- *
- * Implements the `pm eval` command surface (pm-u8n5): a search-relevance
- * evaluation runner that scores a human-curated golden-query set against the
- * live retrieval path and reports nDCG@k, MRR@k, precision@k, and recall@k per
- * query plus the macro average. With `--fail-under` it doubles as a CI gate so
- * relevance regressions — from corpus changes, hybrid-weight changes, or
- * provider swaps (including the offline BM25 provider, pm-75k9) — fail the build
- * instead of silently degrading retrieval quality.
- */
-
-!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]="9cc9405b-d2b8-59aa-893f-54892595788a")}catch(e){}}();
-import { assertInitializedTracker } from "./environment/tracker-preflight.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { aggregateEvalMetrics, DEFAULT_EVAL_K, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, evaluateRanking, parseEvalQuerySet, } from "../core/search/eval.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-import { coercePositiveInteger } from "../core/shared/primitives.js";
-import { resolvePmRoot } from "../core/store/paths.js";
-import { runSearch } from "./query/search.js";
-export { EVAL_QUERY_SET_CONTRACT, EVAL_QUERY_SET_EXAMPLE, EVAL_QUERY_SET_SCHEMA_ID, parseEvalQuerySet, } from "../core/search/eval.js";
-/** Relative location (under the pm root) of the default golden-query set. A git-tracked, human-curated file so relevance ground truth lives alongside the tracker it evaluates. */
-export const DEFAULT_EVAL_QUERIES_RELATIVE_PATH = path.join("search", "eval-queries.json");
-/** Actionable context attached to every query-set loading or validation error. */
-const EVAL_QUERY_SET_ERROR_CONTEXT = {
-    schema: EVAL_QUERY_SET_SCHEMA_ID,
-    examples: [JSON.stringify(EVAL_QUERY_SET_EXAMPLE)],
-    nextSteps: [
-        "Create a git-tracked golden-query JSON file that follows the schema, then re-run pm eval.",
-    ],
-};
-const VALID_EVAL_MODES = new Set([
-    "keyword",
-    "semantic",
-    "hybrid",
-]);
-/** Resolves and validates the default retrieval mode for an evaluation run. */
-const parseEvalMode = (raw) => {
-    if (raw === undefined) {
-        return "keyword";
-    }
-    const normalized = raw.trim().toLowerCase();
-    if (!VALID_EVAL_MODES.has(normalized)) {
-        throw new PmCliError("Eval --mode must be one of keyword|semantic|hybrid", EXIT_CODE.USAGE);
-    }
-    return normalized;
-};
-/** Resolves and validates the positive ranking cutoff for an evaluation run. */
-const parseEvalK = (raw) => {
-    if (raw === undefined || raw === "") {
-        return DEFAULT_EVAL_K;
-    }
-    const parsed = coercePositiveInteger(raw);
-    if (parsed === null) {
-        throw new PmCliError("Eval --k must be a positive integer", EXIT_CODE.USAGE);
-    }
-    return parsed;
-};
-/** Resolves and validates an optional normalized nDCG gate threshold. */
-const parseFailUnder = (raw) => {
-    if (raw === undefined || raw === "") {
-        return undefined;
-    }
-    const normalized = String(raw).trim();
-    const parsed = Number(normalized);
-    if ([
-        normalized.length === 0,
-        !Number.isFinite(parsed),
-        parsed < 0,
-        parsed > 1,
-    ].includes(true)) {
-        throw new PmCliError("Eval --fail-under must be a number in the range [0, 1]", EXIT_CODE.USAGE);
-    }
-    return parsed;
-};
-/** Round a metric to four decimals to keep the JSON output compact and stable. */
-const roundMetric = (value) => Math.round(value * 10_000) / 10_000;
-/** Reads a golden-query file and translates missing-file failures to CLI guidance. */
-const readEvalQuerySetFile = async (queriesPath) => {
-    try {
-        return await fs.readFile(queriesPath, "utf8");
-    }
-    catch {
-        throw new PmCliError(`Eval query set not found at ${queriesPath}`, EXIT_CODE.NOT_FOUND, {
-            ...EVAL_QUERY_SET_ERROR_CONTEXT,
-            examples: [
-                `echo '${JSON.stringify(EVAL_QUERY_SET_EXAMPLE)}' > ${queriesPath}`,
-                "pm eval --queries ./my-eval.json",
-            ],
-        });
-    }
-};
-/** Parses golden-query JSON while preserving a path-specific usage diagnostic. */
-const parseEvalQuerySetJson = (raw, queriesPath) => {
-    try {
-        return JSON.parse(raw);
-    }
-    catch (error) {
-        throw new PmCliError(
-        /* c8 ignore next -- JSON.parse throws Error instances; String fallback protects nonstandard hosts. */
-        `Eval query set at ${queriesPath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.USAGE, EVAL_QUERY_SET_ERROR_CONTEXT);
-    }
-};
-/** Applies the structured golden-query contract and preserves its diagnostics. */
-const validateEvalQuerySet = (parsed) => {
-    try {
-        return parseEvalQuerySet(parsed);
-    }
-    catch (error) {
-        throw new PmCliError(
-        /* c8 ignore next -- parseEvalQuerySet throws Error instances; String fallback protects nonstandard hosts. */
-        error instanceof Error ? error.message : String(error), EXIT_CODE.USAGE, EVAL_QUERY_SET_ERROR_CONTEXT);
-    }
-};
-/** Loads and validates a golden-query set from one resolved filesystem path. */
-const loadEvalQuerySet = async (queriesPath) => validateEvalQuerySet(parseEvalQuerySetJson(await readEvalQuerySetFile(queriesPath), queriesPath));
-/** Resolves the caller override or tracker-owned default golden-query path. */
-const resolveEvalQueriesPath = (pmRoot, queries) => queries
-    ? path.resolve(process.cwd(), queries)
-    : path.join(pmRoot, DEFAULT_EVAL_QUERIES_RELATIVE_PATH);
-/** Executes and scores one golden query without rounding its aggregate input. */
-const evaluateEvalQuery = async (evalQuery, defaultMode, k, global) => {
-    const mode = evalQuery.mode ?? defaultMode;
-    const searchResult = await runSearch(evalQuery.query, { mode, limit: String(k), fields: "id" }, global);
-    const rankedIds = searchResult.items
-        .map((item) => item.id)
-        .filter((id) => typeof id === "string");
-    const metrics = evaluateRanking(rankedIds, new Set(evalQuery.relevant_ids), k);
-    return {
-        metrics,
-        report: {
-            query: evalQuery.query,
-            mode,
-            relevant_total: metrics.relevant_total,
-            retrieved_relevant: metrics.retrieved_relevant,
-            ndcg: roundMetric(metrics.ndcg),
-            mrr: roundMetric(metrics.mrr),
-            precision: roundMetric(metrics.precision),
-            recall: roundMetric(metrics.recall),
-        },
-    };
-};
-/** Shapes rounded aggregate metrics and the optional gate result. */
-const buildEvalResult = (k, reports, rawMetrics, failUnder) => {
-    const aggregate = aggregateEvalMetrics(rawMetrics);
-    return {
-        k,
-        query_count: reports.length,
-        aggregate: {
-            ndcg: roundMetric(aggregate.ndcg),
-            mrr: roundMetric(aggregate.mrr),
-            precision: roundMetric(aggregate.precision),
-            recall: roundMetric(aggregate.recall),
-        },
-        queries: reports,
-        ...(failUnder !== undefined ? { fail_under: failUnder } : {}),
-        passed: failUnder === undefined || aggregate.ndcg >= failUnder,
-    };
-};
-/**
- * Run the search-relevance evaluation (pm-u8n5). Loads the golden-query set
- * (default `<pmRoot>/search/eval-queries.json`, overridable via `--queries`),
- * runs each query through {@link runSearch} at the resolved mode, scores the
- * returned ranking with the nDCG/MRR/precision/recall metrics, and macro-averages
- * across queries. When `--fail-under` is supplied, `passed` reflects whether the
- * aggregate nDCG@k cleared the threshold; the CLI layer maps a failed gate to a
- * non-zero exit code.
- */
-export const runEval = async (options, global) => {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const k = parseEvalK(options.k);
-    const defaultMode = parseEvalMode(options.mode);
-    const failUnder = parseFailUnder(options.failUnder);
-    const queriesPath = resolveEvalQueriesPath(pmRoot, options.queries);
-    const querySet = await loadEvalQuerySet(queriesPath);
-    const reports = [];
-    // Aggregate and gate on the UNROUNDED metrics; rounding is applied only to the
-    // emitted report values so display precision never flips a --fail-under decision.
-    const rawMetrics = [];
-    for (const evalQuery of querySet.queries) {
-        const { report, metrics } = await evaluateEvalQuery(evalQuery, defaultMode, k, global);
-        rawMetrics.push(metrics);
-        reports.push(report);
-    }
-    return buildEvalResult(k, reports, rawMetrics, failUnder);
-};
+!(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]="7f6cfdef-5456-5716-9067-8ccadf077f5f")}catch(e2){}})();import{assertInitializedTracker}from"./environment/tracker-preflight.js";import fs from"node:fs/promises";import path from"node:path";import{aggregateEvalMetrics,DEFAULT_EVAL_K,EVAL_QUERY_SET_EXAMPLE,EVAL_QUERY_SET_SCHEMA_ID,evaluateRanking,parseEvalQuerySet}from"../core/search/eval.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{coercePositiveInteger}from"../core/shared/primitives.js";import{resolvePmRoot}from"../core/store/paths.js";import{runSearch}from"./query/search.js";import{EVAL_QUERY_SET_CONTRACT,EVAL_QUERY_SET_EXAMPLE as EVAL_QUERY_SET_EXAMPLE2,EVAL_QUERY_SET_SCHEMA_ID as EVAL_QUERY_SET_SCHEMA_ID2,parseEvalQuerySet as parseEvalQuerySet2}from"../core/search/eval.js";const DEFAULT_EVAL_QUERIES_RELATIVE_PATH=path.join("search","eval-queries.json");const EVAL_QUERY_SET_ERROR_CONTEXT={schema:EVAL_QUERY_SET_SCHEMA_ID,examples:[JSON.stringify(EVAL_QUERY_SET_EXAMPLE)],nextSteps:["Create a git-tracked golden-query JSON file that follows the schema, then re-run pm eval."]};const VALID_EVAL_MODES=new Set(["keyword","semantic","hybrid"]);const parseEvalMode=raw=>{if(raw===void 0){return"keyword"}const normalized=raw.trim().toLowerCase();if(!VALID_EVAL_MODES.has(normalized)){throw new PmCliError("Eval --mode must be one of keyword|semantic|hybrid",EXIT_CODE.USAGE)}return normalized};const parseEvalK=raw=>{if(raw===void 0||raw===""){return DEFAULT_EVAL_K}const parsed=coercePositiveInteger(raw);if(parsed===null){throw new PmCliError("Eval --k must be a positive integer",EXIT_CODE.USAGE)}return parsed};const parseFailUnder=raw=>{if(raw===void 0||raw===""){return void 0}const normalized=String(raw).trim();const parsed=Number(normalized);if([normalized.length===0,!Number.isFinite(parsed),parsed<0,parsed>1].includes(true)){throw new PmCliError("Eval --fail-under must be a number in the range [0, 1]",EXIT_CODE.USAGE)}return parsed};const roundMetric=value=>Math.round(value*1e4)/1e4;const readEvalQuerySetFile=async queriesPath=>{try{return await fs.readFile(queriesPath,"utf8")}catch{throw new PmCliError(`Eval query set not found at ${queriesPath}`,EXIT_CODE.NOT_FOUND,{...EVAL_QUERY_SET_ERROR_CONTEXT,examples:[`echo '${JSON.stringify(EVAL_QUERY_SET_EXAMPLE)}' > ${queriesPath}`,"pm eval --queries ./my-eval.json"]})}};const parseEvalQuerySetJson=(raw,queriesPath)=>{try{return JSON.parse(raw)}catch(error){throw new PmCliError(`Eval query set at ${queriesPath} is not valid JSON: ${error instanceof Error?error.message:String(error)}`,EXIT_CODE.USAGE,EVAL_QUERY_SET_ERROR_CONTEXT)}};const validateEvalQuerySet=parsed=>{try{return parseEvalQuerySet(parsed)}catch(error){throw new PmCliError(error instanceof Error?error.message:String(error),EXIT_CODE.USAGE,EVAL_QUERY_SET_ERROR_CONTEXT)}};const loadEvalQuerySet=async queriesPath=>validateEvalQuerySet(parseEvalQuerySetJson(await readEvalQuerySetFile(queriesPath),queriesPath));const resolveEvalQueriesPath=(pmRoot,queries)=>queries?path.resolve(process.cwd(),queries):path.join(pmRoot,DEFAULT_EVAL_QUERIES_RELATIVE_PATH);const evaluateEvalQuery=async(evalQuery,defaultMode,k,global2)=>{const mode=evalQuery.mode??defaultMode;const searchResult=await runSearch(evalQuery.query,{mode,limit:String(k),fields:"id"},global2);const rankedIds=searchResult.items.map(item=>item.id).filter(id=>typeof id==="string");const metrics=evaluateRanking(rankedIds,new Set(evalQuery.relevant_ids),k);return{metrics,report:{query:evalQuery.query,mode,relevant_total:metrics.relevant_total,retrieved_relevant:metrics.retrieved_relevant,ndcg:roundMetric(metrics.ndcg),mrr:roundMetric(metrics.mrr),precision:roundMetric(metrics.precision),recall:roundMetric(metrics.recall)}}};const buildEvalResult=(k,reports,rawMetrics,failUnder)=>{const aggregate=aggregateEvalMetrics(rawMetrics);return{k,query_count:reports.length,aggregate:{ndcg:roundMetric(aggregate.ndcg),mrr:roundMetric(aggregate.mrr),precision:roundMetric(aggregate.precision),recall:roundMetric(aggregate.recall)},queries:reports,...failUnder!==void 0?{fail_under:failUnder}:{},passed:failUnder===void 0||aggregate.ndcg>=failUnder}};const runEval=async(options,global2)=>{const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const k=parseEvalK(options.k);const defaultMode=parseEvalMode(options.mode);const failUnder=parseFailUnder(options.failUnder);const queriesPath=resolveEvalQueriesPath(pmRoot,options.queries);const querySet=await loadEvalQuerySet(queriesPath);const reports=[];const rawMetrics=[];for(const evalQuery of querySet.queries){const{report,metrics}=await evaluateEvalQuery(evalQuery,defaultMode,k,global2);rawMetrics.push(metrics);reports.push(report)}return buildEvalResult(k,reports,rawMetrics,failUnder)};export{DEFAULT_EVAL_QUERIES_RELATIVE_PATH,EVAL_QUERY_SET_CONTRACT,EVAL_QUERY_SET_EXAMPLE2 as EVAL_QUERY_SET_EXAMPLE,EVAL_QUERY_SET_SCHEMA_ID2 as EVAL_QUERY_SET_SCHEMA_ID,parseEvalQuerySet2 as parseEvalQuerySet,runEval};
 //# sourceMappingURL=eval.js.map
-//# debugId=9cc9405b-d2b8-59aa-893f-54892595788a

package/dist/sdk/extension/author-manifest.js

@@ -1,93 +1,2 @@
-/**
- * @module sdk/extension/author-manifest
- *
- * Reads the optional extension manifest at a package-author workspace root and
- * projects the public schema lint into health/doctor diagnostics.
- */
-
-!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]="5755dee7-d2df-5ced-8a94-aeb51762edb7")}catch(e){}}();
-import fs from "node:fs/promises";
-import path from "node:path";
-import { isFileAbsentError } from "../../core/fs/fs-utils.js";
-import { lintExtensionManifestSchema, } from "../../core/extensions/manifest-schema.js";
-import { resolveWorkspaceRoot } from "../../core/store/paths.js";
-function manifestName(raw) {
-    return typeof raw.name === "string" && raw.name.trim().length > 0
-        ? raw.name.trim()
-        : "workspace-manifest";
-}
-function authorManifestWarning(name, finding) {
-    return finding.code === "manifest_unknown_key"
-        ? `extension_manifest_unknown_key:author:${name}:key=${finding.path}${finding.suggested_key ? `:suggested=${finding.suggested_key}` : ""}`
-        : `extension_manifest_no_version_bounds:author:${name}:suggested=pm_min_version`;
-}
-/** Inspect `<workspace>/manifest.json` without loading extension code. */
-export async function inspectExtensionAuthorManifest(workspaceRoot) {
-    const manifestPath = path.join(workspaceRoot, "manifest.json");
-    let content;
-    try {
-        content = await fs.readFile(manifestPath, "utf8");
-    }
-    catch (error) {
-        if (isFileAbsentError(error)) {
-            return {
-                path: manifestPath,
-                present: false,
-                parse_status: "absent",
-                package_metadata_location: "package.json#pm",
-                schema_findings: [],
-                warnings: [],
-                remediation: [],
-            };
-        }
-        throw error;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(content);
-    }
-    catch {
-        return {
-            path: manifestPath,
-            present: true,
-            parse_status: "invalid_json",
-            package_metadata_location: "package.json#pm",
-            schema_findings: [],
-            warnings: ["extension_author_manifest_invalid_json:manifest.json"],
-            remediation: [
-                "Repair manifest.json so it contains one valid JSON object, then rerun pm package doctor --project.",
-            ],
-        };
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return {
-            path: manifestPath,
-            present: true,
-            parse_status: "invalid_shape",
-            package_metadata_location: "package.json#pm",
-            schema_findings: [],
-            warnings: ["extension_author_manifest_invalid_shape:manifest.json"],
-            remediation: [
-                "Replace manifest.json with one JSON object, then rerun pm package doctor --project.",
-            ],
-        };
-    }
-    const raw = parsed;
-    const lint = lintExtensionManifestSchema(raw);
-    const name = manifestName(raw);
-    return {
-        path: manifestPath,
-        present: true,
-        parse_status: "valid",
-        package_metadata_location: "package.json#pm",
-        schema_findings: lint.findings,
-        warnings: lint.findings.map((finding) => authorManifestWarning(name, finding)),
-        remediation: lint.findings.map((finding) => finding.message),
-    };
-}
-/** Inspect the author manifest for a resolved project tracker root. */
-export function inspectExtensionAuthorManifestAtPmRoot(pmRoot) {
-    return inspectExtensionAuthorManifest(resolveWorkspaceRoot(pmRoot));
-}
+!(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]="b1bf79a0-1f04-590f-b613-45ca1b534d5d")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{isFileAbsentError}from"../../core/fs/fs-utils.js";import{lintExtensionManifestSchema}from"../../core/extensions/manifest-schema.js";import{resolveWorkspaceRoot}from"../../core/store/paths.js";function manifestName(raw){return typeof raw.name==="string"&&raw.name.trim().length>0?raw.name.trim():"workspace-manifest"}function authorManifestWarning(name,finding){return finding.code==="manifest_unknown_key"?`extension_manifest_unknown_key:author:${name}:key=${finding.path}${finding.suggested_key?`:suggested=${finding.suggested_key}`:""}`:`extension_manifest_no_version_bounds:author:${name}:suggested=pm_min_version`}async function inspectExtensionAuthorManifest(workspaceRoot){const manifestPath=path.join(workspaceRoot,"manifest.json");let content;try{content=await fs.readFile(manifestPath,"utf8")}catch(error){if(isFileAbsentError(error)){return{path:manifestPath,present:false,parse_status:"absent",package_metadata_location:"package.json#pm",schema_findings:[],warnings:[],remediation:[]}}throw error}let parsed;try{parsed=JSON.parse(content)}catch{return{path:manifestPath,present:true,parse_status:"invalid_json",package_metadata_location:"package.json#pm",schema_findings:[],warnings:["extension_author_manifest_invalid_json:manifest.json"],remediation:["Repair manifest.json so it contains one valid JSON object, then rerun pm package doctor --project."]}}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){return{path:manifestPath,present:true,parse_status:"invalid_shape",package_metadata_location:"package.json#pm",schema_findings:[],warnings:["extension_author_manifest_invalid_shape:manifest.json"],remediation:["Replace manifest.json with one JSON object, then rerun pm package doctor --project."]}}const raw=parsed;const lint=lintExtensionManifestSchema(raw);const name=manifestName(raw);return{path:manifestPath,present:true,parse_status:"valid",package_metadata_location:"package.json#pm",schema_findings:lint.findings,warnings:lint.findings.map(finding=>authorManifestWarning(name,finding)),remediation:lint.findings.map(finding=>finding.message)}}function inspectExtensionAuthorManifestAtPmRoot(pmRoot){return inspectExtensionAuthorManifest(resolveWorkspaceRoot(pmRoot))}export{inspectExtensionAuthorManifest,inspectExtensionAuthorManifestAtPmRoot};
 //# sourceMappingURL=author-manifest.js.map
-//# debugId=5755dee7-d2df-5ced-8a94-aeb51762edb7