@stigmer/cli 3.16.0 → 3.16.1-dev.20260917224426

package/src/marketplace/install.test.ts

@@ -0,0 +1,194 @@
+// Pins how a ref becomes a prepared push: an offered entry prepares through
+// the same walker `push plugin` uses (one digest for one tree); a version
+// pin is an assertion; a bare name is searched across the configured
+// marketplaces and must land in exactly one; every temp tree a search opened
+// is disposed, whatever the outcome.
+
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { zipSync } from "fflate";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { preparePluginPush } from "../resources/plugin.js";
+import { writeCursorMarketplace } from "./__fixtures__/cursor-marketplace.js";
+import { type MarketplaceListing, OFFICIAL_MARKETPLACE } from "./config.js";
+import { assertVersion, locateEntry, prepareEntry } from "./install.js";
+import { readMarketplaceTree } from "./read.js";
+import { parseInstallRef } from "./ref.js";
+
+let root: string;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "stigmer-marketplace-install-"));
+  writeCursorMarketplace(root);
+});
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("prepareEntry", () => {
+  it("prepares an offered entry exactly as push plugin would prepare its directory", async () => {
+    const tree = readMarketplaceTree(root);
+    const viaMarketplace = await prepareEntry(tree, "github");
+    const viaFolder = await preparePluginPush(join(root, "third_party", "github"));
+    expect(viaMarketplace.plugin.name).toBe("github");
+    expect(viaMarketplace.digest).toBe(viaFolder.digest);
+    expect(
+      Buffer.from(viaMarketplace.archive).equals(
+        Buffer.from(viaFolder.archive),
+      ),
+    ).toBe(true);
+  });
+
+  it("refuses an entry the marketplace does not offer, quoting the drop sentence when there is one", async () => {
+    const tree = readMarketplaceTree(root);
+    await expect(prepareEntry(tree, "ghost")).rejects.toThrow(
+      /does not offer a plugin named 'ghost'\n\n.*ghost.*\n\nRun 'stigmer marketplace show cursor-plugins' to see the 2 it offers/s,
+    );
+    await expect(prepareEntry(tree, "nope")).rejects.toThrow(
+      /does not offer a plugin named 'nope'\n\nRun 'stigmer marketplace show/,
+    );
+  });
+});
+
+describe("assertVersion", () => {
+  it("passes without a pin or with the offered version, refuses another naming the offered one", async () => {
+    const prepared = await prepareEntry(readMarketplaceTree(root), "thermos");
+    expect(() => assertVersion(prepared, undefined, "thermos")).not.toThrow();
+    expect(() =>
+      assertVersion(prepared, "1.0.0", "thermos@1.0.0"),
+    ).not.toThrow();
+    expect(() =>
+      assertVersion(prepared, "9.9.9", "cursor-plugins/thermos@9.9.9"),
+    ).toThrow(
+      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0\n\nInstall it as 'cursor-plugins\/thermos@1\.0\.0'/,
+    );
+  });
+});
+
+describe("locateEntry", () => {
+  const encoder = new TextEncoder();
+
+  /** A GitHub source served from memory: the fixture tree zipped under one top directory. */
+  function servingZipOf(
+    files: Record<string, string>,
+    top = "r-HEAD",
+  ): typeof globalThis.fetch {
+    const tree: Record<string, Uint8Array> = {};
+    for (const [path, content] of Object.entries(files))
+      tree[`${top}/${path}`] = encoder.encode(content);
+    const bytes = zipSync(tree);
+    return async () => new Response(bytes, { status: 200 });
+  }
+
+  const remoteFiles = {
+    "marketplace.json": JSON.stringify({
+      name: "remote",
+      plugins: [{ name: "thermos", source: "./thermos" }],
+    }),
+    "thermos/plugin.json": JSON.stringify({
+      name: "thermos",
+      version: "3.0.0",
+    }),
+  };
+
+  function listing(...extra: MarketplaceListing["known"]): MarketplaceListing {
+    return { known: [OFFICIAL_MARKETPLACE, ...extra], unreadable: [] };
+  }
+
+  it("opens the marketplace a prefixed ref names and refuses an unknown prefix", async () => {
+    const local = {
+      name: "cursor-plugins",
+      source: { type: "local", path: root } as const,
+    };
+    const located = await locateEntry(
+      parseInstallRef("cursor-plugins/thermos"),
+      listing(local),
+    );
+    try {
+      expect(located.marketplace.name).toBe("cursor-plugins");
+      expect(located.tree.root).toBe(root);
+    } finally {
+      located.open.dispose();
+    }
+    await expect(
+      locateEntry(parseInstallRef("nowhere/thermos"), listing(local)),
+    ).rejects.toThrow(/no marketplace named 'nowhere' is configured/);
+  });
+
+  it("searches a bare name across every marketplace and lands in the one holder, disposing the rest", async () => {
+    const local = {
+      name: "cursor-plugins",
+      source: { type: "local", path: root } as const,
+    };
+    const located = await locateEntry(
+      parseInstallRef("github"),
+      listing(local),
+    );
+    try {
+      expect(located.marketplace.name).toBe("cursor-plugins");
+    } finally {
+      located.open.dispose();
+    }
+  });
+
+  it("refuses a bare name nobody offers, naming what was searched and what could not be read", async () => {
+    const local = {
+      name: "cursor-plugins",
+      source: { type: "local", path: root } as const,
+    };
+    await expect(
+      locateEntry(parseInstallRef("nope"), {
+        known: [OFFICIAL_MARKETPLACE, local],
+        unreadable: [{ name: "broken", reason: "x" }],
+      }),
+    ).rejects.toThrow(
+      /no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, cursor-plugins\. Not searched.*broken/,
+    );
+  });
+
+  it("refuses a bare name two marketplaces offer, naming each qualified ref, and leaves no temp tree behind", async () => {
+    const local = {
+      name: "cursor-plugins",
+      source: { type: "local", path: root } as const,
+    };
+    const remote = {
+      name: "remote",
+      source: { type: "github", repo: "a/b" } as const,
+    };
+    const before = countTempTrees();
+    await expect(
+      locateEntry(parseInstallRef("thermos"), listing(local, remote), {
+        fetchImpl: servingZipOf(remoteFiles),
+      }),
+    ).rejects.toThrow(
+      /offered by more than one marketplace: cursor-plugins, remote\n\nName the one you mean: cursor-plugins\/thermos or remote\/thermos/,
+    );
+    expect(countTempTrees()).toBe(before);
+  });
+
+  it("disposes a fetched tree when the located entry is released", async () => {
+    const remote = {
+      name: "remote",
+      source: { type: "github", repo: "a/b" } as const,
+    };
+    const located = await locateEntry(
+      parseInstallRef("remote/thermos"),
+      listing(remote),
+      {
+        fetchImpl: servingZipOf(remoteFiles),
+      },
+    );
+    expect(existsSync(located.tree.root)).toBe(true);
+    located.open.dispose();
+    expect(existsSync(located.tree.root)).toBe(false);
+  });
+});
+
+/** The temp trees `openMarketplace` creates (`stigmer-marketplace-` plus mkdtemp's suffix and nothing else). */
+function countTempTrees(): number {
+  return readdirSync(tmpdir()).filter((name) =>
+    /^stigmer-marketplace-[A-Za-z0-9]+$/.test(name),
+  ).length;
+}

package/src/marketplace/install.ts

@@ -0,0 +1,159 @@
+// An entry of an open marketplace becomes a prepared push. This is the one
+// place that happens, for both callers: `stigmer install <ref>` and the
+// `stigmer up` default-set step. Neither re-derives the entry's directory or
+// the archive's digest; both hand the prepared value to `pushPrepared` (or,
+// for `up`, compare its digest first). The entry's directory goes through the
+// same walker `push plugin <dir>` uses, so a marketplace install and a push
+// of the same checked-out folder yield one digest for one tree.
+
+import { type MarketplaceEntry } from "@stigmer/plugin-package";
+import { UsageError } from "../errors/index.js";
+import {
+  type PreparedPluginPush,
+  preparePluginPush,
+} from "../resources/plugin.js";
+import {
+  type KnownMarketplace,
+  type MarketplaceListing,
+  describeSource,
+} from "./config.js";
+import {
+  type OpenMarketplace,
+  type OpenMarketplaceOptions,
+  openMarketplace,
+} from "./materialize.js";
+import {
+  type ReadMarketplaceTree,
+  entryDirectory,
+  findEntry,
+  readMarketplaceTree,
+} from "./read.js";
+import { type InstallRef, formatInstallRef } from "./ref.js";
+
+/** A ref resolved to the one marketplace that offers it, with that marketplace open on disk. */
+export interface LocatedEntry {
+  readonly marketplace: KnownMarketplace;
+  readonly open: OpenMarketplace;
+  readonly tree: ReadMarketplaceTree;
+}
+
+/**
+ * Find the marketplace a ref names. A prefixed ref names it outright; a bare
+ * name is searched across every configured marketplace in listing order
+ * (the official one first), and exactly one must offer it: none refuses
+ * toward `marketplace show`, more than one refuses by naming each holder,
+ * because "the first one wins" would make the answer depend on the order
+ * the user added marketplaces in. The caller owns `open` and disposes it.
+ */
+export async function locateEntry(
+  ref: InstallRef,
+  listing: MarketplaceListing,
+  options: OpenMarketplaceOptions = {},
+): Promise<LocatedEntry> {
+  if (ref.marketplace !== undefined) {
+    const marketplace = listing.known.find(
+      (known) => known.name === ref.marketplace,
+    );
+    if (marketplace === undefined) {
+      throw new UsageError(
+        `no marketplace named '${ref.marketplace}' is configured\n\n` +
+          "Run 'stigmer marketplace list' to see the configured names, or add one with 'stigmer marketplace add <source>'.",
+      );
+    }
+    const open = await openMarketplace(marketplace.source, options);
+    try {
+      const tree = readMarketplaceTree(
+        open.root,
+        describeSource(marketplace.source),
+      );
+      if (findEntry(tree.marketplace, ref.name) === undefined)
+        throw entryNotOffered(tree, ref.name);
+      return { marketplace, open, tree };
+    } catch (error) {
+      open.dispose();
+      throw error;
+    }
+  }
+
+  const holders: LocatedEntry[] = [];
+  for (const marketplace of listing.known) {
+    const open = await openMarketplace(marketplace.source, options);
+    let tree: ReadMarketplaceTree;
+    try {
+      tree = readMarketplaceTree(open.root, describeSource(marketplace.source));
+    } catch (error) {
+      open.dispose();
+      for (const holder of holders) holder.open.dispose();
+      throw error;
+    }
+    if (findEntry(tree.marketplace, ref.name) === undefined) {
+      open.dispose();
+      continue;
+    }
+    holders.push({ marketplace, open, tree });
+  }
+  if (holders.length === 1) return holders[0]!;
+  for (const holder of holders) holder.open.dispose();
+  if (holders.length === 0) {
+    const skipped =
+      listing.unreadable.length === 0
+        ? ""
+        : ` Not searched, because its entry cannot be read: ${listing.unreadable.map((entry) => entry.name).join(", ")} (see 'stigmer marketplace list').`;
+    throw new UsageError(
+      `no configured marketplace offers a plugin named '${ref.name}'\n\n` +
+        `Searched: ${listing.known.map((known) => known.name).join(", ")}.${skipped} ` +
+        "Run 'stigmer marketplace show <name>' to see what each offers, or add the marketplace that has it.",
+    );
+  }
+  throw new UsageError(
+    `'${ref.name}' is offered by more than one marketplace: ${holders.map((holder) => holder.marketplace.name).join(", ")}\n\n` +
+      `Name the one you mean: ${holders.map((holder) => formatInstallRef({ ...ref, marketplace: holder.marketplace.name })).join(" or ")}.`,
+  );
+}
+
+/** Read, validate and zip the entry called `name`; refuses an entry the marketplace does not offer. */
+export async function prepareEntry(
+  tree: ReadMarketplaceTree,
+  name: string,
+): Promise<PreparedPluginPush> {
+  const entry = findEntry(tree.marketplace, name);
+  if (entry === undefined) throw entryNotOffered(tree, name);
+  return preparePluginPush(entryDirectory(tree, entry));
+}
+
+/**
+ * `@version` in a ref is an assertion, not a selector: a marketplace tree
+ * holds one version of each plugin, so the ref either names it or is wrong.
+ */
+export function assertVersion(
+  prepared: PreparedPluginPush,
+  wanted: string | undefined,
+  ref: string,
+): void {
+  if (wanted === undefined) return;
+  const offered = prepared.plugin.version;
+  if (offered === wanted) return;
+  throw new UsageError(
+    offered === undefined
+      ? `'${ref}' pins version ${wanted}, but the marketplace's '${prepared.plugin.name}' declares no version\n\nInstall it without '@${wanted}'.`
+      : `'${ref}' pins version ${wanted}, but the marketplace offers '${prepared.plugin.name}' at ${offered}\n\nInstall it as '${ref.slice(0, ref.lastIndexOf("@"))}@${offered}', or without a version.`,
+  );
+}
+
+function entryNotOffered(tree: ReadMarketplaceTree, name: string): UsageError {
+  const dropped = tree.warnings.find((warning) => warning.subject === name);
+  const offered = tree.marketplace.plugins.map(
+    (entry: MarketplaceEntry) => entry.name,
+  );
+  const lines = [
+    `marketplace '${tree.marketplace.name}' does not offer a plugin named '${name}'`,
+  ];
+  if (dropped !== undefined) lines.push("", dropped.message);
+  lines.push(
+    "",
+    offered.length === 0
+      ? "It offers no plugins this CLI can install."
+      : `Run 'stigmer marketplace show ${tree.marketplace.name}' to see the ${offered.length} it offers.`,
+  );
+  return new UsageError(lines.join("\n"));
+}

package/src/marketplace/materialize.ts

@@ -0,0 +1,80 @@
+// Every marketplace source becomes a directory, and every directory is read by
+// the one plugin walker. This module is where a source turns into that
+// directory and where the directory's lifetime is owned: a local path is used
+// where it is; the official tree is resolved or acquired; a GitHub zipball is
+// extracted under a temp directory that `dispose` removes. One owner for the
+// lifetime means `add`, `show` and `install` cannot leak a temp tree between
+// them, whatever path an error takes.
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { MarketplaceSource } from "./config.js";
+import { fetchGitHubTree } from "./github.js";
+import {
+  type ResolveOfficialOptions,
+  resolveOfficialMarketplace,
+} from "./official.js";
+
+/** A marketplace tree on disk, for as long as the caller holds it. */
+export interface OpenMarketplace {
+  /** Absolute path to the tree root: the directory the marketplace file sits in. */
+  readonly root: string;
+  /** Release whatever the open created (a temp directory); a no-op for a tree that was already there. */
+  dispose(): void;
+}
+
+export interface OpenMarketplaceOptions {
+  /** The HTTP client for GitHub sources (injectable for tests). */
+  readonly fetchImpl?: typeof globalThis.fetch;
+  /** How the official tree is found (injectable for tests). */
+  readonly official?: ResolveOfficialOptions;
+}
+
+export async function openMarketplace(
+  source: MarketplaceSource,
+  options: OpenMarketplaceOptions = {},
+): Promise<OpenMarketplace> {
+  switch (source.type) {
+    case "local":
+      return { root: source.path, dispose: () => {} };
+    case "official":
+      return {
+        root: resolveOfficialMarketplace(options.official).dir,
+        dispose: () => {},
+      };
+    case "github": {
+      const root = mkdtempSync(join(tmpdir(), "stigmer-marketplace-"));
+      const dispose = (): void =>
+        rmSync(root, { recursive: true, force: true });
+      try {
+        await fetchGitHubTree(source, {
+          destDir: root,
+          fetchImpl: options.fetchImpl,
+        });
+      } catch (error) {
+        dispose();
+        throw error;
+      }
+      return { root, dispose };
+    }
+    default: {
+      const exhaustive: never = source;
+      return exhaustive;
+    }
+  }
+}
+
+/** Open, hand the tree to `use`, and dispose whatever the outcome. */
+export async function withMarketplace<T>(
+  source: MarketplaceSource,
+  use: (open: OpenMarketplace) => Promise<T> | T,
+  options: OpenMarketplaceOptions = {},
+): Promise<T> {
+  const open = await openMarketplace(source, options);
+  try {
+    return await use(open);
+  } finally {
+    open.dispose();
+  }
+}

package/src/marketplace/official.test.ts

@@ -0,0 +1,107 @@
+// Pins the official marketplace's resolution: the repo tree wins when this
+// module runs from a checkout; otherwise the package is acquired once at the
+// CLI's version into the runtimes root, reused on the next call, and refused
+// for a non-release build that has nothing installed.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  acquireOfficialMarketplace,
+  resolveOfficialMarketplace,
+} from "./official.js";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "stigmer-official-marketplace-"));
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+function fakeInstall(installDir: string): void {
+  const pkg = join(installDir, "node_modules", "@stigmer", "plugins");
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, "marketplace.json"),
+    JSON.stringify({ name: "stigmer", plugins: [] }),
+  );
+}
+
+describe("resolveOfficialMarketplace", () => {
+  it("uses the repo tree when running from a checkout", () => {
+    const resolved = resolveOfficialMarketplace({ home });
+    expect(resolved.source).toBe("repo");
+    expect(resolved.dir.endsWith(join("", "plugins"))).toBe(true);
+  });
+
+  it("acquires the package when there is no checkout, once, and reuses it", () => {
+    let installs = 0;
+    const install = (installDir: string): void => {
+      installs += 1;
+      fakeInstall(installDir);
+    };
+    const first = resolveOfficialMarketplace({
+      home,
+      version: "1.2.3",
+      install,
+      repoDir: () => null,
+    });
+    const second = resolveOfficialMarketplace({
+      home,
+      version: "1.2.3",
+      install,
+      repoDir: () => null,
+    });
+    expect(first.source).toBe("package");
+    expect(first.dir).toBe(
+      join(
+        home,
+        ".stigmer",
+        "runtimes",
+        "1.2.3",
+        "node_modules",
+        "@stigmer",
+        "plugins",
+      ),
+    );
+    expect(second.dir).toBe(first.dir);
+    expect(installs).toBe(1);
+  });
+});
+
+describe("acquireOfficialMarketplace", () => {
+  it("refuses to acquire for a non-release build with nothing installed", () => {
+    expect(() =>
+      acquireOfficialMarketplace({
+        home,
+        version: "0.0.0-dev",
+        install: () => {},
+      }),
+    ).toThrow(/cannot acquire @stigmer\/plugins for a non-release build/);
+  });
+
+  it("uses already-installed content even for a non-release build", () => {
+    const installDir = join(home, ".stigmer", "runtimes", "0.0.0-dev");
+    fakeInstall(installDir);
+    let installs = 0;
+    const dir = acquireOfficialMarketplace({
+      home,
+      version: "0.0.0-dev",
+      install: () => {
+        installs += 1;
+      },
+    });
+    expect(dir).toBe(join(installDir, "node_modules", "@stigmer", "plugins"));
+    expect(installs).toBe(0);
+  });
+
+  it("refuses when the install did not produce the marketplace file", () => {
+    expect(() =>
+      acquireOfficialMarketplace({ home, version: "1.2.3", install: () => {} }),
+    ).toThrow(/install did not produce/);
+  });
+});

package/src/marketplace/official.ts

@@ -0,0 +1,125 @@
+// Resolution and on-demand acquisition of the official marketplace.
+//
+// The official catalogue (`plugins/` in the OSS repository, published as
+// `@stigmer/plugins`) is the content `stigmer up` bootstraps a backend with,
+// so it follows the seedpack's rule: acquired at the CLI's OWN version, so
+// the plugins a fresh install gets match the control plane that installs
+// them. A lean `npx @stigmer/cli` does not carry the content; it is fetched
+// once into ~/.stigmer/runtimes/<version>/ like the server and the runner.
+//
+// Two sources, tried in order (mirrors runtime/server.ts and the seedpack):
+//   1. A repo-tree checkout (dev): `<repo>/plugins`, the tree itself.
+//   2. The published `@stigmer/plugins@<cli-version>`, whose package root IS
+//      the marketplace tree (`publish-libs.mjs` publishes from `dist/`, where
+//      `stage-content.mjs` placed `marketplace.json` and every listed plugin).
+//
+// Presence beats acquirability (the server acquirer's rule): installed content
+// is used whatever its version string; only an install we would have to
+// perform is refused for a non-release build. The all-in-one image relies on
+// this: it bakes the package at a dev-stamped version npm never published.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MARKETPLACE_LOCATIONS } from "@stigmer/plugin-package";
+import { CliExitError } from "../errors/cli-exit-error.js";
+import { ExitCode } from "../errors/exit-codes.js";
+import { log } from "../logger.js";
+import { runtimesDir } from "../local/paths.js";
+import {
+  ensureRuntimesRoot,
+  isAcquirableRelease,
+  npmInstallIntoRuntimes,
+  type NpmInstall,
+} from "../local/runtime/runtimes-install.js";
+import { VERSION } from "../version.js";
+
+const PLUGINS_PACKAGE = "@stigmer/plugins";
+
+/** The file that makes a directory the official tree: Stigmer's own marketplace dialect at the root. */
+const OFFICIAL_MARKER = MARKETPLACE_LOCATIONS.stigmer;
+
+export interface OfficialMarketplaceDir {
+  /** Absolute path to the tree root (holds `marketplace.json`). */
+  readonly dir: string;
+  /** Where the tree came from, for diagnostics. */
+  readonly source: "repo" | "package";
+}
+
+export interface ResolveOfficialOptions {
+  home?: string;
+  /** Release version of `@stigmer/plugins` to acquire (defaults to the CLI version). */
+  version?: string;
+  /** npm install implementation (injectable for tests). */
+  install?: NpmInstall;
+  /** The repo-tree probe (injectable for tests; the default walks up from this module). */
+  repoDir?: () => string | null;
+}
+
+/**
+ * The official marketplace's directory: a repo-tree checkout in dev, else the
+ * on-demand-acquired package. Throws actionable guidance when acquisition is
+ * not possible (a non-release build with no checkout, a failed install).
+ */
+export function resolveOfficialMarketplace(
+  opts: ResolveOfficialOptions = {},
+): OfficialMarketplaceDir {
+  const repo = (opts.repoDir ?? repoPluginsDir)();
+  if (repo !== null) return { dir: repo, source: "repo" };
+  return { dir: acquireOfficialMarketplace(opts), source: "package" };
+}
+
+/**
+ * Acquire `@stigmer/plugins@<version>` into ~/.stigmer/runtimes/<version>/
+ * (idempotent) and return the package directory, which is the tree root.
+ */
+export function acquireOfficialMarketplace(
+  opts: ResolveOfficialOptions = {},
+): string {
+  const home = opts.home ?? homedir();
+  const version = opts.version ?? VERSION;
+
+  const installDir = join(runtimesDir(home), version);
+  const pkgDir = join(installDir, "node_modules", "@stigmer", "plugins");
+  const marker = join(pkgDir, OFFICIAL_MARKER);
+
+  if (!existsSync(marker)) {
+    if (!isAcquirableRelease(version)) {
+      throw new CliExitError(
+        `cannot acquire ${PLUGINS_PACKAGE} for a non-release build (${version})`,
+        ExitCode.General,
+        [
+          "Run from the repo (the plugins/ tree is used directly in dev).",
+          "On-demand acquisition is only available for published releases.",
+        ],
+      );
+    }
+    log.info(`acquiring ${PLUGINS_PACKAGE}`, { version, dir: installDir });
+    ensureRuntimesRoot(installDir);
+    const install = opts.install ?? npmInstallIntoRuntimes;
+    install(installDir, `${PLUGINS_PACKAGE}@${version}`);
+  }
+
+  if (!existsSync(marker)) {
+    throw new CliExitError(
+      `${PLUGINS_PACKAGE} install did not produce ${marker}`,
+      ExitCode.General,
+      [`Remove ${installDir} and retry.`],
+    );
+  }
+  return pkgDir;
+}
+
+// Walk up from this module to a repo root whose plugins/ holds the marker.
+function repoPluginsDir(): string | null {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 10; i += 1) {
+    const candidate = join(dir, "plugins");
+    if (existsSync(join(candidate, OFFICIAL_MARKER))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}