@unbrained/pm-cli 2026.6.19 → 2026.6.21

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

@@ -0,0 +1,62 @@
+import { type EvalSearchMode } from "../../core/search/eval.js";
+import type { GlobalOptions } from "../../core/shared/command-types.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 declare const DEFAULT_EVAL_QUERIES_RELATIVE_PATH: string;
+/**
+ * Documents the eval command options payload exchanged by command, SDK, and package integrations.
+ */
+export interface EvalOptions {
+    /** Default retrieval mode for queries that do not set their own (keyword|semantic|hybrid). */
+    mode?: string;
+    /** Metric cutoff (`@k`); positive integer, defaults to {@link DEFAULT_EVAL_K}. */
+    k?: string | number;
+    /** Gate threshold: exit non-zero when the aggregate nDCG@k falls below this `[0,1]` value. */
+    failUnder?: string | number;
+    /** Override path to the golden-query JSON file (defaults to `<pmRoot>/search/eval-queries.json`). */
+    queries?: string;
+    /** Output format override: json|toon. */
+    format?: string;
+}
+/** Per-query relevance report row emitted by {@link runEval}. */
+export interface EvalQueryReport {
+    query: string;
+    mode: EvalSearchMode;
+    relevant_total: number;
+    retrieved_relevant: number;
+    ndcg: number;
+    mrr: number;
+    precision: number;
+    recall: number;
+}
+/**
+ * Documents the eval result payload exchanged by command, SDK, and package integrations.
+ */
+export interface EvalResult {
+    k: number;
+    query_count: number;
+    aggregate: {
+        ndcg: number;
+        mrr: number;
+        precision: number;
+        recall: number;
+    };
+    queries: EvalQueryReport[];
+    /** Present only when `--fail-under` was supplied. */
+    fail_under?: number;
+    /** Whether the aggregate nDCG met the gate (always true when no gate is set). */
+    passed: boolean;
+}
+/**
+ * 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 declare function runEval(options: EvalOptions, global: GlobalOptions): Promise<EvalResult>;

package/dist/cli/commands/eval.js

@@ -0,0 +1,158 @@
+/**
+ * @module cli/commands/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]="fa1fece2-ddfb-537d-af39-fcd4ab8b5972")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { aggregateEvalMetrics, DEFAULT_EVAL_K, 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 { pathExists } from "../../core/fs/fs-utils.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { runSearch } from "./search.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");
+const VALID_EVAL_MODES = new Set(["keyword", "semantic", "hybrid"]);
+function 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;
+}
+function 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;
+}
+function parseFailUnder(raw) {
+    if (raw === undefined || raw === "") {
+        return undefined;
+    }
+    const parsed = typeof raw === "number" ? raw : Number(String(raw).trim());
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        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. */
+function roundMetric(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+async function loadEvalQuerySet(queriesPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(queriesPath, "utf8");
+    }
+    catch {
+        throw new PmCliError(`Eval query set not found at ${queriesPath}`, EXIT_CODE.NOT_FOUND, {
+            examples: [
+                'echo \'[{"query":"offline search","relevant_ids":["pm-75k9"]}]\' > ' + queriesPath,
+                "pm eval --queries ./my-eval.json",
+            ],
+            nextSteps: [
+                "Create a git-tracked golden-query JSON file (an array of {query, relevant_ids, mode?} objects), then re-run pm eval.",
+            ],
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        // JSON.parse only ever throws a SyntaxError (an Error subclass).
+        throw new PmCliError(`Eval query set at ${queriesPath} is not valid JSON: ${error.message}`, EXIT_CODE.USAGE);
+    }
+    try {
+        return parseEvalQuerySet(parsed);
+    }
+    catch (error) {
+        // parseEvalQuerySet only ever throws EvalQuerySetError (an Error subclass
+        // with a precise, author-actionable message) — surface it as a usage error.
+        throw new PmCliError(error.message, EXIT_CODE.USAGE);
+    }
+}
+/**
+ * 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 async function runEval(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const k = parseEvalK(options.k);
+    const defaultMode = parseEvalMode(options.mode);
+    const failUnder = parseFailUnder(options.failUnder);
+    const queriesPath = options.queries
+        ? path.resolve(process.cwd(), options.queries)
+        : path.join(pmRoot, DEFAULT_EVAL_QUERIES_RELATIVE_PATH);
+    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 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);
+        rawMetrics.push(metrics);
+        reports.push({
+            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 aggregate = aggregateEvalMetrics(rawMetrics);
+    const passed = failUnder === undefined || aggregate.ndcg >= failUnder;
+    return {
+        k,
+        query_count: querySet.queries.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,
+    };
+}
+//# sourceMappingURL=eval.js.map
+//# debugId=fa1fece2-ddfb-537d-af39-fcd4ab8b5972

package/dist/cli/commands/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sources":["cli/commands/eval.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/eval\n *\n * Implements the `pm eval` command surface (pm-u8n5): a search-relevance\n * evaluation runner that scores a human-curated golden-query set against the\n * live retrieval path and reports nDCG@k, MRR@k, precision@k, and recall@k per\n * query plus the macro average. With `--fail-under` it doubles as a CI gate so\n * relevance regressions — from corpus changes, hybrid-weight changes, or\n * provider swaps (including the offline BM25 provider, pm-75k9) — fail the build\n * instead of silently degrading retrieval quality.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport {\n  aggregateEvalMetrics,\n  DEFAULT_EVAL_K,\n  evaluateRanking,\n  parseEvalQuerySet,\n  type EvalSearchMode,\n  type QueryEvalMetrics,\n} from \"../../core/search/eval.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 { coercePositiveInteger } from \"../../core/shared/primitives.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { runSearch } from \"./search.js\";\n\n/**\n * Relative location (under the pm root) of the default golden-query set. A\n * git-tracked, human-curated file so relevance ground truth lives alongside the\n * tracker it evaluates.\n */\nexport const DEFAULT_EVAL_QUERIES_RELATIVE_PATH = path.join(\"search\", \"eval-queries.json\");\n\n/**\n * Documents the eval command options payload exchanged by command, SDK, and package integrations.\n */\nexport interface EvalOptions {\n  /** Default retrieval mode for queries that do not set their own (keyword|semantic|hybrid). */\n  mode?: string;\n  /** Metric cutoff (`@k`); positive integer, defaults to {@link DEFAULT_EVAL_K}. */\n  k?: string | number;\n  /** Gate threshold: exit non-zero when the aggregate nDCG@k falls below this `[0,1]` value. */\n  failUnder?: string | number;\n  /** Override path to the golden-query JSON file (defaults to `<pmRoot>/search/eval-queries.json`). */\n  queries?: string;\n  /** Output format override: json|toon. */\n  format?: string;\n}\n\n/** Per-query relevance report row emitted by {@link runEval}. */\nexport interface EvalQueryReport {\n  query: string;\n  mode: EvalSearchMode;\n  relevant_total: number;\n  retrieved_relevant: number;\n  ndcg: number;\n  mrr: number;\n  precision: number;\n  recall: number;\n}\n\n/**\n * Documents the eval result payload exchanged by command, SDK, and package integrations.\n */\nexport interface EvalResult {\n  k: number;\n  query_count: number;\n  aggregate: {\n    ndcg: number;\n    mrr: number;\n    precision: number;\n    recall: number;\n  };\n  queries: EvalQueryReport[];\n  /** Present only when `--fail-under` was supplied. */\n  fail_under?: number;\n  /** Whether the aggregate nDCG met the gate (always true when no gate is set). */\n  passed: boolean;\n}\n\nconst VALID_EVAL_MODES: ReadonlySet<string> = new Set<EvalSearchMode>([\"keyword\", \"semantic\", \"hybrid\"]);\n\nfunction parseEvalMode(raw: string | undefined): EvalSearchMode {\n  if (raw === undefined) {\n    return \"keyword\";\n  }\n  const normalized = raw.trim().toLowerCase();\n  if (!VALID_EVAL_MODES.has(normalized)) {\n    throw new PmCliError(\"Eval --mode must be one of keyword|semantic|hybrid\", EXIT_CODE.USAGE);\n  }\n  return normalized as EvalSearchMode;\n}\n\nfunction parseEvalK(raw: string | number | undefined): number {\n  if (raw === undefined || raw === \"\") {\n    return DEFAULT_EVAL_K;\n  }\n  const parsed = coercePositiveInteger(raw);\n  if (parsed === null) {\n    throw new PmCliError(\"Eval --k must be a positive integer\", EXIT_CODE.USAGE);\n  }\n  return parsed;\n}\n\nfunction parseFailUnder(raw: string | number | undefined): number | undefined {\n  if (raw === undefined || raw === \"\") {\n    return undefined;\n  }\n  const parsed = typeof raw === \"number\" ? raw : Number(String(raw).trim());\n  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {\n    throw new PmCliError(\"Eval --fail-under must be a number in the range [0, 1]\", EXIT_CODE.USAGE);\n  }\n  return parsed;\n}\n\n/** Round a metric to four decimals to keep the JSON output compact and stable. */\nfunction roundMetric(value: number): number {\n  return Math.round(value * 10_000) / 10_000;\n}\n\nasync function loadEvalQuerySet(queriesPath: string): Promise<ReturnType<typeof parseEvalQuerySet>> {\n  let raw: string;\n  try {\n    raw = await fs.readFile(queriesPath, \"utf8\");\n  } catch {\n    throw new PmCliError(`Eval query set not found at ${queriesPath}`, EXIT_CODE.NOT_FOUND, {\n      examples: [\n        'echo \\'[{\"query\":\"offline search\",\"relevant_ids\":[\"pm-75k9\"]}]\\' > ' + queriesPath,\n        \"pm eval --queries ./my-eval.json\",\n      ],\n      nextSteps: [\n        \"Create a git-tracked golden-query JSON file (an array of {query, relevant_ids, mode?} objects), then re-run pm eval.\",\n      ],\n    });\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (error: unknown) {\n    // JSON.parse only ever throws a SyntaxError (an Error subclass).\n    throw new PmCliError(\n      `Eval query set at ${queriesPath} is not valid JSON: ${(error as Error).message}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  try {\n    return parseEvalQuerySet(parsed);\n  } catch (error: unknown) {\n    // parseEvalQuerySet only ever throws EvalQuerySetError (an Error subclass\n    // with a precise, author-actionable message) — surface it as a usage error.\n    throw new PmCliError((error as Error).message, EXIT_CODE.USAGE);\n  }\n}\n\n/**\n * Run the search-relevance evaluation (pm-u8n5). Loads the golden-query set\n * (default `<pmRoot>/search/eval-queries.json`, overridable via `--queries`),\n * runs each query through {@link runSearch} at the resolved mode, scores the\n * returned ranking with the nDCG/MRR/precision/recall metrics, and macro-averages\n * across queries. When `--fail-under` is supplied, `passed` reflects whether the\n * aggregate nDCG@k cleared the threshold; the CLI layer maps a failed gate to a\n * non-zero exit code.\n */\nexport async function runEval(options: EvalOptions, global: GlobalOptions): Promise<EvalResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\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  const k = parseEvalK(options.k);\n  const defaultMode = parseEvalMode(options.mode);\n  const failUnder = parseFailUnder(options.failUnder);\n  const queriesPath = options.queries\n    ? path.resolve(process.cwd(), options.queries)\n    : path.join(pmRoot, DEFAULT_EVAL_QUERIES_RELATIVE_PATH);\n  const querySet = await loadEvalQuerySet(queriesPath);\n\n  const reports: EvalQueryReport[] = [];\n  // Aggregate and gate on the UNROUNDED metrics; rounding is applied only to the\n  // emitted report values so display precision never flips a --fail-under decision.\n  const rawMetrics: QueryEvalMetrics[] = [];\n  for (const evalQuery of querySet.queries) {\n    const mode = evalQuery.mode ?? defaultMode;\n    const searchResult = await runSearch(\n      evalQuery.query,\n      { mode, limit: String(k), fields: \"id\" },\n      global,\n    );\n    const rankedIds = searchResult.items\n      .map((item) => (item as { id?: unknown }).id)\n      .filter((id): id is string => typeof id === \"string\");\n    const metrics = evaluateRanking(rankedIds, new Set(evalQuery.relevant_ids), k);\n    rawMetrics.push(metrics);\n    reports.push({\n      query: evalQuery.query,\n      mode,\n      relevant_total: metrics.relevant_total,\n      retrieved_relevant: metrics.retrieved_relevant,\n      ndcg: roundMetric(metrics.ndcg),\n      mrr: roundMetric(metrics.mrr),\n      precision: roundMetric(metrics.precision),\n      recall: roundMetric(metrics.recall),\n    });\n  }\n\n  const aggregate = aggregateEvalMetrics(rawMetrics);\n  const passed = failUnder === undefined || aggregate.ndcg >= failUnder;\n  return {\n    k,\n    query_count: querySet.queries.length,\n    aggregate: {\n      ndcg: roundMetric(aggregate.ndcg),\n      mrr: roundMetric(aggregate.mrr),\n      precision: roundMetric(aggregate.precision),\n      recall: roundMetric(aggregate.recall),\n    },\n    queries: reports,\n    ...(failUnder !== undefined ? { fail_under: failUnder } : {}),\n    passed,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"fa1fece2-ddfb-537d-af39-fcd4ab8b5972"}

package/dist/cli/commands/extension/install-sources.d.ts

@@ -98,6 +98,14 @@ declare function resolveNpmSourceDirectoryWithRunner(source: NpmInstallSource, n
     cleanup: () => Promise<void>;
 }>;
 declare function installNpmPackageRuntimeDependencies(packageRoot: string): Promise<void>;
+declare function hasHostedPmCliDependency(manifest: {
+    dependencies?: unknown;
+    optionalDependencies?: unknown;
+    peerDependencies?: unknown;
+}): boolean;
+declare function removeHostedPmCliDependency(manifest: Record<string, unknown>): void;
+declare function linkHostedPmCliDependency(packageRoot: string): Promise<void>;
+declare function resolveDirectorySymlinkType(platform: NodeJS.Platform): "dir" | "junction";
 declare function runtimeDependencyInstallSpecs(manifest: {
     dependencies?: unknown;
     optionalDependencies?: unknown;
@@ -121,6 +129,10 @@ export declare const _testOnlyInstallSources: {
     resolveNpmPackSpec: typeof resolveNpmPackSpec;
     resolvePackageExtensionDirectory: typeof resolvePackageExtensionDirectory;
     runtimeDependencyInstallSpecs: typeof runtimeDependencyInstallSpecs;
+    hasHostedPmCliDependency: typeof hasHostedPmCliDependency;
+    removeHostedPmCliDependency: typeof removeHostedPmCliDependency;
+    linkHostedPmCliDependency: typeof linkHostedPmCliDependency;
+    resolveDirectorySymlinkType: typeof resolveDirectorySymlinkType;
     runNpmCommand: typeof runNpmCommand;
 };
 export {};

package/dist/cli/commands/extension/install-sources.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Install Sources.
  */
 
-!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]="8d64f224-2711-543f-8c95-dc6517478217")}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]="76ef9a1c-698d-5324-a677-794b015787d5")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -12,11 +12,13 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { collectPackageExtensionDirectories } from "../../../core/packages/manifest.js";
+import { resolvePmPackageRootFromModule } from "../../../core/packages/root.js";
 import { pathExists } from "../../../core/fs/fs-utils.js";
 import { isPathWithinDirectory } from "../../../core/fs/path-utils.js";
 import { EXIT_CODE } from "../../../core/shared/constants.js";
 import { PmCliError } from "../../../core/shared/errors.js";
 const execFileAsync = promisify(execFile);
+const PM_CLI_PACKAGE_NAME = "@unbrained/pm-cli";
 function parseGithubPathSpec(pathSpec, input, refOverride) {
     const segments = pathSpec
         .split("/")
@@ -393,17 +395,75 @@ async function installNpmPackageRuntimeDependencies(packageRoot) {
     }
     const manifest = parsed;
     const dependencySpecs = runtimeDependencyInstallSpecs(manifest);
-    if (dependencySpecs.length === 0) {
+    const shouldLinkHostedPmCli = hasHostedPmCliDependency(manifest);
+    if (dependencySpecs.length === 0 && !shouldLinkHostedPmCli) {
         return;
     }
     const runtimeOnlyManifest = { ...parsed };
     delete runtimeOnlyManifest.devDependencies;
-    await fs.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}\n`, "utf8");
-    await Promise.all([
-        fs.rm(path.join(packageRoot, "package-lock.json"), { force: true }),
-        fs.rm(path.join(packageRoot, "npm-shrinkwrap.json"), { force: true }),
-    ]);
-    await runNpmCommand(["install", "--ignore-scripts", "--no-audit", "--fund=false", "--package-lock=false", "--no-save", ...dependencySpecs], packageRoot);
+    const installManifest = { ...runtimeOnlyManifest };
+    removeHostedPmCliDependency(installManifest);
+    await fs.writeFile(packageJsonPath, `${JSON.stringify(installManifest, null, 2)}\n`, "utf8");
+    try {
+        await Promise.all([
+            fs.rm(path.join(packageRoot, "package-lock.json"), { force: true }),
+            fs.rm(path.join(packageRoot, "npm-shrinkwrap.json"), { force: true }),
+        ]);
+        if (dependencySpecs.length > 0) {
+            await runNpmCommand([
+                "install",
+                "--ignore-scripts",
+                "--no-audit",
+                "--fund=false",
+                "--package-lock=false",
+                "--no-save",
+                "--omit=peer",
+                ...dependencySpecs,
+            ], packageRoot);
+        }
+        if (shouldLinkHostedPmCli) {
+            await linkHostedPmCliDependency(packageRoot);
+        }
+    }
+    finally {
+        await fs.writeFile(packageJsonPath, `${JSON.stringify(runtimeOnlyManifest, null, 2)}\n`, "utf8");
+    }
+}
+function hasHostedPmCliDependency(manifest) {
+    for (const dependencyMap of [manifest.dependencies, manifest.optionalDependencies, manifest.peerDependencies]) {
+        if (typeof dependencyMap === "object" && dependencyMap !== null && PM_CLI_PACKAGE_NAME in dependencyMap) {
+            return true;
+        }
+    }
+    return false;
+}
+function removeHostedPmCliDependency(manifest) {
+    for (const field of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+        const dependencyMap = manifest[field];
+        if (typeof dependencyMap !== "object" || dependencyMap === null) {
+            continue;
+        }
+        const nextMap = { ...dependencyMap };
+        delete nextMap[PM_CLI_PACKAGE_NAME];
+        if (Object.keys(nextMap).length === 0) {
+            delete manifest[field];
+        }
+        else {
+            manifest[field] = nextMap;
+        }
+    }
+}
+async function linkHostedPmCliDependency(packageRoot) {
+    const hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, ["../../../.."]);
+    const [scope, packageName] = PM_CLI_PACKAGE_NAME.split("/");
+    const scopedDirectory = path.join(packageRoot, "node_modules", scope);
+    const linkPath = path.join(scopedDirectory, packageName);
+    await fs.mkdir(scopedDirectory, { recursive: true });
+    await fs.rm(linkPath, { recursive: true, force: true });
+    await fs.symlink(hostPackageRoot, linkPath, resolveDirectorySymlinkType(process.platform));
+}
+function resolveDirectorySymlinkType(platform) {
+    return platform === "win32" ? "junction" : "dir";
 }
 function runtimeDependencyInstallSpecs(manifest) {
     const specs = new Map();
@@ -412,7 +472,10 @@ function runtimeDependencyInstallSpecs(manifest) {
             continue;
         }
         for (const [name, version] of Object.entries(dependencyMap)) {
-            if (typeof version !== "string" || version.trim().length === 0 || specs.has(name)) {
+            if (name === PM_CLI_PACKAGE_NAME ||
+                typeof version !== "string" ||
+                version.trim().length === 0 ||
+                specs.has(name)) {
                 continue;
             }
             specs.set(name, `${name}@${version.trim()}`);
@@ -539,7 +602,11 @@ export const _testOnlyInstallSources = {
     resolveNpmPackSpec,
     resolvePackageExtensionDirectory,
     runtimeDependencyInstallSpecs,
+    hasHostedPmCliDependency,
+    removeHostedPmCliDependency,
+    linkHostedPmCliDependency,
+    resolveDirectorySymlinkType,
     runNpmCommand,
 };
 //# sourceMappingURL=install-sources.js.map
-//# debugId=8d64f224-2711-543f-8c95-dc6517478217
+//# debugId=76ef9a1c-698d-5324-a677-794b015787d5