@hienlh/ppm 0.23.6 → 0.23.8

package/src/services/fs-ops/fs-ops-trash.service.ts

@@ -47,28 +47,40 @@ function osaLiteral(value: string): string {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
 
-function windowsCommand(path: string, isDirectory: boolean): string[] {
+/**
+ * How a backend binary is found, replaceable for the same reason `TrashRunner` is.
+ *
+ * Which tool is present is as much a property of the host as what running it does, and
+ * leaving the lookup outside the seam meant a test could fake the run and still be refused
+ * before reaching it — on any machine without `gio` or `trash-put`, which includes the
+ * container the suite runs in.
+ */
+export type TrashLookup = (name: string) => string | null;
+
+const defaultLookup: TrashLookup = (name) => Bun.which(name);
+
+function windowsCommand(path: string, isDirectory: boolean, which: TrashLookup): string[] {
   const method = isDirectory ? "DeleteDirectory" : "DeleteFile";
   const script =
     "Add-Type -AssemblyName Microsoft.VisualBasic; " +
     `[Microsoft.VisualBasic.FileIO.FileSystem]::${method}(${psLiteral(path)},'OnlyErrorDialogs','SendToRecycleBin')`;
-  const shell = Bun.which("powershell") ?? Bun.which("pwsh");
+  const shell = which("powershell") ?? which("pwsh");
   if (!shell) throw noTrash("powershell not found on PATH");
   return [shell, "-NoProfile", "-NonInteractive", "-Command", script];
 }
 
 /** Paths are always absolute here, so no leading-dash option confusion. */
-function posixCommand(path: string): string[] {
+function posixCommand(path: string, which: TrashLookup): string[] {
   if (process.platform === "darwin") {
-    const trash = Bun.which("trash");
+    const trash = which("trash");
     if (trash) return [trash, path];
-    const osascript = Bun.which("osascript");
+    const osascript = which("osascript");
     if (!osascript) throw noTrash("neither trash nor osascript found on PATH");
     return [osascript, "-e", `tell application "Finder" to delete POSIX file ${osaLiteral(path)}`];
   }
-  const gio = Bun.which("gio");
+  const gio = which("gio");
   if (gio) return [gio, "trash", path];
-  const trashPut = Bun.which("trash-put");
+  const trashPut = which("trash-put");
   if (trashPut) return [trashPut, path];
   throw noTrash("neither gio nor trash-put found on PATH");
 }
@@ -85,7 +97,7 @@ async function isDirectoryTarget(path: string): Promise<boolean> {
 
 export async function trashPath(
   path: string,
-  options?: { run?: TrashRunner },
+  options?: { run?: TrashRunner; which?: TrashLookup },
 ): Promise<{ trashed: true; path: string }> {
   const target = resolvePath(path);
   assertAllowed(target);
@@ -94,8 +106,9 @@ export async function trashPath(
   await assertNotProtected(target);
   const isDir = await isDirectoryTarget(target);
 
+  const which = options?.which ?? defaultLookup;
   const cmd =
-    process.platform === "win32" ? windowsCommand(target, isDir) : posixCommand(target);
+    process.platform === "win32" ? windowsCommand(target, isDir, which) : posixCommand(target, which);
 
   const run = options?.run ?? spawnRunner;
   let result: { exitCode: number; stderr: string };

package/src/services/git-refs/for-each-ref.ts

@@ -0,0 +1,118 @@
+/**
+ * Every checkout target — local branches, remote-tracking branches and tags —
+ * out of a single `git for-each-ref`, with the commit each one points at.
+ *
+ * The format string is built from the field list rather than written out,
+ * because the parser reads fields *positionally*: a field added to one and not
+ * the other shifts everything after it, and git answers just as happily either
+ * way — the picker would simply show a date where the author belongs, with
+ * nothing failing.
+ *
+ * Six of the twelve fields are the `*`-dereferenced twins of six others, and
+ * they are what makes an **annotated** tag readable. `refs/tags/v1` resolves to
+ * the tag *object*, not to a commit: its `objectname` is the tag's own hash,
+ * it has a tagger rather than an author (so `%(authorname)` and
+ * `%(committerdate)` come back empty) and its `contents:subject` is the tag
+ * message. A lightweight tag has no such object and leaves every `*` field
+ * empty — which is why each pair is resolved as "dereferenced when non-empty,
+ * else plain" rather than by asking what kind of ref it is.
+ */
+import type { GitRef } from "../../types/git.ts";
+
+const FIELDS = [
+  "refname",
+  "objectname",
+  "*objectname",
+  "HEAD",
+  "upstream:short",
+  "upstream:track",
+  "authorname",
+  "*authorname",
+  "committerdate:iso-strict",
+  "*committerdate:iso-strict",
+  "contents:subject",
+  "*contents:subject",
+] as const;
+
+/** NUL between fields, newline between records: no ref name or subject may contain either. */
+export const FOR_EACH_REF_FORMAT = FIELDS.map((f) => `%(${f})`).join("%00");
+
+export const FOR_EACH_REF_ARGS = [
+  "for-each-ref",
+  `--format=${FOR_EACH_REF_FORMAT}`,
+  "refs/heads",
+  "refs/remotes",
+  "refs/tags",
+];
+
+const PREFIX: Record<GitRef["type"], string> = {
+  branch: "refs/heads/",
+  remote: "refs/remotes/",
+  tag: "refs/tags/",
+};
+
+/**
+ * `%(upstream:track)` as git writes it: `[ahead 1, behind 26]`, either half on
+ * its own, `[gone]` when the remote branch was deleted, or empty when the
+ * branch has no upstream at all.
+ */
+export function parseUpstreamTrack(track: string): Pick<GitRef, "ahead" | "behind" | "gone"> {
+  if (track.includes("gone")) return { ahead: 0, behind: 0, gone: true };
+  const ahead = /ahead (\d+)/.exec(track);
+  const behind = /behind (\d+)/.exec(track);
+  return {
+    ahead: ahead ? Number(ahead[1]) : 0,
+    behind: behind ? Number(behind[1]) : 0,
+    gone: false,
+  };
+}
+
+function refType(refName: string): GitRef["type"] | null {
+  for (const [type, prefix] of Object.entries(PREFIX)) {
+    if (refName.startsWith(prefix)) return type as GitRef["type"];
+  }
+  return null;
+}
+
+/** Newest commit first. Compared as instants, never as strings: `iso-strict` carries the author's own offset. */
+function newestFirst(a: GitRef, b: GitRef): number {
+  const at = Date.parse(a.date);
+  const bt = Date.parse(b.date);
+  if (Number.isNaN(at) || Number.isNaN(bt)) return a.name.localeCompare(b.name);
+  return bt - at;
+}
+
+export function parseForEachRef(stdout: string): GitRef[] {
+  const refs: GitRef[] = [];
+
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const f = line.split("\0");
+    // A short record means a field carried a newline after all. Skipping it
+    // loses one row; reading it would silently shift every field of that row.
+    if (f.length < FIELDS.length) continue;
+
+    const refName = f[0]!;
+    const type = refType(refName);
+    if (!type) continue;
+    // `origin/HEAD` is a symbolic pointer at another row of this same list.
+    if (type === "remote" && refName.endsWith("/HEAD")) continue;
+
+    const hash = f[2] || f[1]!;
+    refs.push({
+      refName,
+      name: refName.slice(PREFIX[type].length),
+      type,
+      current: f[3] === "*",
+      hash,
+      shortHash: hash.slice(0, 7),
+      subject: f[11] || f[10]!,
+      author: f[7] || f[6]!,
+      date: f[9] || f[8]!,
+      upstream: f[4] || null,
+      ...parseUpstreamTrack(f[5]!),
+    });
+  }
+
+  return refs.sort(newestFirst);
+}

package/src/services/git.service.ts

@@ -1,13 +1,16 @@
 import path from "node:path";
 import simpleGit, { type SimpleGit } from "simple-git";
 import { isBinaryContent } from "./binary-content.ts";
+import { FOR_EACH_REF_ARGS, parseForEachRef } from "./git-refs/for-each-ref.ts";
 import type {
+  CheckoutMode,
   FileFullDiff,
   GitStatus,
   GitFileChange,
   GitCommit,
   GitBranch,
   GitGraphData,
+  GitRef,
   GitWorktree,
 } from "../types/git.ts";
 
@@ -319,8 +322,28 @@ class GitService {
     await this.git(projectPath).checkoutBranch(name, from ?? "HEAD");
   }
 
-  async checkout(projectPath: string, ref: string): Promise<void> {
-    await this.git(projectPath).checkout(ref);
+  /**
+   * `track` is not a nicety: `git checkout origin/foo` lands on a **detached
+   * HEAD**, because the remote-tracking ref is not a branch anyone can commit
+   * to. `-t` is what creates the local `foo` that follows it. The picker
+   * chooses between the three modes; the service only has to keep them apart.
+   */
+  async checkout(
+    projectPath: string,
+    ref: string,
+    mode: CheckoutMode = "checkout",
+  ): Promise<void> {
+    const flags = mode === "detach" ? ["--detach"] : mode === "track" ? ["-t"] : [];
+    // `--` or the ref is read as a pathspec when no such ref exists: `git checkout src`
+    // in a repository with no branch named `src` restores every unstaged change under
+    // that directory, silently and with exit 0. `assertSafeRev` refuses a leading dash
+    // and a range, but a plain directory name is a legitimate ref shape.
+    await this.git(projectPath).checkout([...flags, ref, "--"]);
+  }
+
+  /** Every local branch, remote-tracking branch and tag, newest commit first. */
+  async refs(projectPath: string): Promise<GitRef[]> {
+    return parseForEachRef(await this.git(projectPath).raw(FOR_EACH_REF_ARGS));
   }
 
   async deleteBranch(

package/src/services/host-info/spawn-runner.ts

@@ -13,10 +13,37 @@ export type Runner = (argv: string[], timeoutMs?: number) => Promise<RunResult>;
 
 const DEFAULT_TIMEOUT_MS = 5000;
 
-/** Real implementation: argv array only (never string-interpolated into a shell), bounded by timeoutMs. */
+/** Real implementation: argv array only (never string-interpolated into a shell), bounded by timeoutMs.
+ *
+ *  `Bun.spawn` **throws synchronously** when the binary is not on `PATH`
+ *  ("Executable not found in $PATH"), and for these providers that is a normal
+ *  condition rather than an error: every one of them shells out to a per-OS tool
+ *  (`systemctl`, `plutil`, `powershell.exe`, `findmnt`, `xdg-user-dir`,
+ *  `nvidia-smi`), so on any other OS the binary is simply absent. Left to throw,
+ *  it escapes the `Promise<RunResult>` this signature promises: the Services page
+ *  on macOS and Windows answered 500 and showed the exception, instead of the
+ *  "this host has no service manager" the collector is written to report.
+ *
+ *  So a missing binary is returned as a run that failed — `code: null` with the
+ *  message on stderr, which is the shape every caller already handles for a
+ *  non-zero exit. */
+const spawnPiped = (argv: string[]) =>
+  Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+
 export const defaultRunner: Runner = async (argv, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-  const proc = Bun.spawn(argv, { stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+  // Named via `spawnPiped` rather than `ReturnType<typeof Bun.spawn>`: the bare
+  // form loses the option narrowing, and `proc.stdout` widens back to a union
+  // with `number` (a raw fd) that `new Response()` will not take.
+  let proc: ReturnType<typeof spawnPiped>;
+  try {
+    proc = spawnPiped(argv);
+  } catch (e: any) {
+    return { stdout: "", stderr: e?.message ?? String(e), code: null, timedOut: false };
+  }
   let timedOut = false;
+  /** Resolves when the timeout fires, so the readers below stop waiting with the process. */
+  let giveUp!: () => void;
+  const abandoned = new Promise<void>((resolve) => { giveUp = resolve; });
   const killTimer = setTimeout(() => {
     timedOut = true;
     try {
@@ -24,12 +51,29 @@ export const defaultRunner: Runner = async (argv, timeoutMs = DEFAULT_TIMEOUT_MS
     } catch {
       // Process already exited between the timer firing and the kill call.
     }
+    giveUp();
   }, timeoutMs);
 
+  /**
+   * The output, or nothing once the run has been given up on.
+   *
+   * Killing the process does **not** close its pipes. A shell that forks rather than execs
+   * leaves a grandchild holding the write end, so draining stdout goes on until *that* exits —
+   * measured, `proc.exited` came back at the 150ms timeout while the drain ran the full five
+   * seconds, which means `timeoutMs` bounded nothing at all. The pending read is left to settle
+   * on its own and discarded rather than cancelled: cancelling a subprocess stream has crashed
+   * Bun on Windows before, and there is nothing here worth that risk.
+   */
+  const readOrAbandon = (stream: ReadableStream<Uint8Array>): Promise<string> =>
+    Promise.race([
+      new Response(stream).text().catch(() => ""),
+      abandoned.then(() => ""),
+    ]);
+
   try {
     const [stdout, stderr, code] = await Promise.all([
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
+      readOrAbandon(proc.stdout),
+      readOrAbandon(proc.stderr),
       proc.exited,
     ]);
     return { stdout, stderr, code, timedOut };

package/src/services/jsonl-transcript-parser.ts

@@ -9,6 +9,8 @@ import { homedir } from "node:os";
 import type { ChatEvent, ChatMessage } from "../types/chat.ts";
 import { stringifyToolResultContent } from "../shared/tool-result-content.ts";
 import { stripSharedContext } from "../shared/provider-context.ts";
+import { readLines } from "./read-lines.ts";
+import { readCompactions, applyCompactions } from "./compaction-savings.ts";
 
 /**
  * How large a transcript this module will look at, for the callers that go
@@ -307,48 +309,6 @@ export function validateJsonlPath(inputPath: string, maxBytes = MAX_FILE_SIZE):
   return real;
 }
 
-/**
- * Yield a file's lines without holding the file in memory.
- *
- * `Bun.file().text()` plus `split("\n")` costs the whole transcript twice over —
- * 277MB resident for a 77MB file, which is what forced a cap low enough to
- * reject real sessions. Peak here is one chunk plus one line.
- */
-async function* readLines(filePath: string, fromByte = 0): AsyncGenerator<string> {
-  const decoder = new TextDecoder();
-  // Explicit reader rather than `for await` over the stream: the DOM lib's
-  // ReadableStream is not typed as async-iterable, and the `finally` is what
-  // releases it when a caller breaks early on `beforeUuid`.
-  // One byte *before* the offset, so the first line the split produces is
-  // always the tail of the record the offset fell inside — the empty string
-  // when it fell exactly on a newline. That makes the drop below unconditional
-  // instead of a boundary case, and a boundary case here silently costs a whole
-  // record rather than a fragment.
-  const file = fromByte > 0 ? Bun.file(filePath).slice(fromByte - 1) : Bun.file(filePath);
-  const reader = file.stream().getReader();
-  // A fragment is not always unparseable — the tail of one record is sometimes
-  // a complete smaller document — so it has to go by position rather than be
-  // left for `JSON.parse` to reject, or it enters as an invented message.
-  let dropPartial = fromByte > 0;
-  let buffered = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffered += decoder.decode(value, { stream: true });
-      const lines = buffered.split("\n");
-      buffered = lines.pop() ?? "";
-      for (const line of lines) {
-        if (dropPartial) { dropPartial = false; continue; }
-        yield line;
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  buffered += decoder.decode();
-  if (buffered && !dropPartial) yield buffered;
-}
 
 /**
  * Read a JSONL transcript file, parse entries, apply merge/nest pipeline, return ChatMessage[].
@@ -418,6 +378,11 @@ export async function parseJsonlTranscript(
   const { mergeSubagentChildren } = await import("./subagent-transcript-merger.ts");
   mergeSubagentChildren(filePath.replace(/\.jsonl$/, ""), merged);
 
+  // An expanded segment opens with its own compact summary, so it needs the same
+  // divider the newest one gets — otherwise only the last compaction in a chat is
+  // labelled and the earlier ones read as ordinary messages.
+  applyCompactions(merged, await readCompactions(filePath).catch(() => new Map()));
+
   return merged.filter(
     (msg) => msg.content.trim().length > 0 || (msg.events && msg.events.length > 0),
   );

package/src/services/lsp/lsp-install.ts

@@ -0,0 +1,289 @@
+/**
+ * Installing a language server, when someone presses Install.
+ *
+ * Nothing here runs because a file was opened. The editor says which server is missing and
+ * offers the button; pressing it is the consent, and that is the whole difference between this
+ * and an editor that fetches a binary off the network on its own.
+ *
+ * Four decisions worth keeping:
+ *
+ * - **Into `<ppm dir>/lsp-servers`, never `-g` and never `~/go/bin`.** A global
+ *   `bun add typescript@5` replaces whatever TypeScript the user had installed globally, and a
+ *   global bin directory is only found when it happens to be on the *service's* PATH — which
+ *   for a systemd-started PPM is four entries and nothing of the sort. PPM's own directory is
+ *   neither, `PPM_HOME` already isolates it for tests, and deleting it is the whole uninstall.
+ *   `rustup` is the one exception, below.
+ * - **The packages come from the registry, by server id.** Nothing the browser sends is ever
+ *   part of a command, so the route cannot be talked into installing something else.
+ * - **PPM installs servers, never toolchains.** `go install` needs a Go and
+ *   `rustup component add` needs a rustup; where the host has neither, there is no button at
+ *   all rather than one that fails when pressed.
+ * - **The directory gets a `package.json` before `bun add` runs.** Measured: `bun add` in a
+ *   directory with no manifest does not create one there — it walks *up* to the nearest parent
+ *   that has one and installs into that, leaving the directory it was asked about empty.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveBunPath } from "../autostart-generator.ts";
+import { getPpmDir } from "../ppm-dir.ts";
+import {
+  installedBinaryPath,
+  installedServerEntry,
+  packageName,
+  type LanguageServerDefinition,
+  type LanguageServerInstall,
+} from "./server-registry.ts";
+
+/** Generous: a cold `go install` builds the server from source. 10.6 s here, minutes elsewhere. */
+const INSTALL_TIMEOUT_MS = 5 * 60_000;
+/** `rustup which` is a lookup, not work. Measured at 3 ms; anything near this is a hung host. */
+const QUERY_TIMEOUT_MS = 10_000;
+
+/** Where the Install button puts servers. Inside the PPM dir, so `PPM_HOME` isolates it. */
+export function lspInstallDir(): string {
+  return path.join(getPpmDir(), "lsp-servers");
+}
+
+export interface RunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * How this module runs a command.
+ *
+ * One injectable seam for all of it, so a test can drive an install with no toolchain on the
+ * machine — and named rather than `typeof Bun.spawn`, whose type widens the pipes back to a
+ * union with a raw file descriptor that `new Response()` will not take.
+ */
+export type Runner = (
+  cmd: string[],
+  options: { cwd: string; env?: Record<string, string | undefined>; timeoutMs: number },
+) => Promise<RunResult>;
+
+const runCommand: Runner = async (cmd, { cwd, env, timeoutMs }) => {
+  const proc = Bun.spawn(cmd, { cwd, env: env as Record<string, string> | undefined, stdout: "pipe", stderr: "pipe" });
+  const timer = setTimeout(() => proc.kill(), timeoutMs);
+  // Drained while it runs: a pipe nobody reads fills up, and a full pipe blocks the child
+  // instead of failing it, so awaiting the exit first can wait forever on a noisy install.
+  const [code, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  clearTimeout(timer);
+  return { code, stdout, stderr };
+};
+
+/**
+ * The binary that would carry out this plan, or null where the host has none.
+ *
+ * The lookup is `PATH`, deliberately: it is the same PATH a language server PPM starts will
+ * inherit, so a host where PPM cannot see the Go toolchain is also a host where gopls could
+ * not run `go list`. Offering the button there would install a server that cannot work.
+ */
+export function installToolPath(plan: LanguageServerInstall): string | null {
+  if (plan.with === "bun") {
+    try {
+      return resolveBunPath();
+    } catch {
+      return null; // a compiled PPM on a host with no bun
+    }
+  }
+  // The PATH is passed explicitly because `Bun.which` otherwise reads the one the *process
+  // started with* and never looks at `process.env.PATH` again — measured: adding a directory to
+  // it changes nothing, and neither does emptying it. The tool is then spawned by the absolute
+  // path this returns, so the lookup and the run can never disagree.
+  return Bun.which(plan.with === "go" ? "go" : "rustup", { PATH: process.env.PATH ?? "" });
+}
+
+/** Whether the Install button can work here. The editor draws the button from this. */
+export function canInstall(definition: LanguageServerDefinition): boolean {
+  return definition.install ? installToolPath(definition.install) !== null : false;
+}
+
+/**
+ * Where rustup says this server is, or null when the component is not installed.
+ *
+ * `rustup which` is both the lookup and the installed-check, and it has to be: the proxy in
+ * `~/.cargo/bin` exists whether or not the component does — measured on this host, with no
+ * rust-analyzer installed, `~/.cargo/bin/rust-analyzer` is right there pointing at rustup — so
+ * a path test would report a server that cannot start. It answers in 3 ms, and it answers for
+ * the toolchain `cwd` selects, which a symlink made at install time could not.
+ */
+export async function rustupServerPath(
+  definition: LanguageServerDefinition,
+  cwd: string,
+  run: Runner = runCommand,
+): Promise<string | null> {
+  if (definition.install?.with !== "rustup") return null;
+  const rustup = installToolPath(definition.install);
+  if (!rustup) return null;
+  try {
+    const result = await run([rustup, "which", definition.command], { cwd, timeoutMs: QUERY_TIMEOUT_MS });
+    const found = result.stdout.trim();
+    return result.code === 0 && found ? found : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One at a time: every install and uninstall shares one `package.json`, lockfile and toolchain. */
+let queue: Promise<unknown> = Promise.resolve();
+/** Keyed by operation *and* id, so a second Uninstall click joins that uninstall — never an install. */
+const inFlight = new Map<string, Promise<void>>();
+
+/**
+ * Install one server, and resolve once it is really there.
+ *
+ * Two clicks on one button — a second tab, an impatient user — join the same install rather
+ * than starting a second one over the first one's lockfile.
+ */
+export function installLanguageServer(
+  definition: LanguageServerDefinition,
+  options: { projectPath?: string; run?: Runner } = {},
+): Promise<void> {
+  return enqueue(`install:${definition.id}`, () => install(definition, options.projectPath, options.run ?? runCommand));
+}
+
+/**
+ * Remove one server, running the exact inverse of what installed it.
+ *
+ * Offered only for a server PPM itself put there, which is a question about where it was
+ * *found* rather than about what is on this machine — `lsp-manager.availability` answers it
+ * with `origin`, and the route gates on that. A copy on `PATH` is the user's, one in a
+ * project's `node_modules` is the repository's, and the one PPM ships is its own dependency:
+ * deleting any of the three would be PPM tidying up after someone else.
+ *
+ * rustup is again the exception that reaches outside PPM's directory, for the same reason
+ * installing it did — the component belongs to a toolchain and there is no copy of PPM's to
+ * delete. Removing it is one `rustup component add` away from being back.
+ */
+export function uninstallLanguageServer(
+  definition: LanguageServerDefinition,
+  options: { projectPath?: string; run?: Runner } = {},
+): Promise<void> {
+  return enqueue(`uninstall:${definition.id}`, () => uninstall(definition, options.projectPath, options.run ?? runCommand));
+}
+
+function enqueue(key: string, work: () => Promise<void>): Promise<void> {
+  const existing = inFlight.get(key);
+  if (existing) return existing;
+
+  const started = queue.then(work);
+  queue = started.catch(() => {}); // a failure must not poison the queue behind it
+  const tracked = started.finally(() => inFlight.delete(key));
+  inFlight.set(key, tracked);
+  return tracked;
+}
+
+async function install(definition: LanguageServerDefinition, projectPath: string | undefined, run: Runner): Promise<void> {
+  const plan = definition.install;
+  if (!plan) throw new Error(`PPM cannot install ${definition.displayName}`);
+  const tool = installToolPath(plan);
+  if (!tool) {
+    throw new Error(`${plan.with} is not installed on this host, so PPM cannot install ${definition.displayName}.`);
+  }
+
+  const dir = lspInstallDir();
+  const failed = (result: RunResult, what: string) => new Error(`${what} failed to install: ${output(result)}`);
+
+  if (plan.with === "bun") {
+    ensureInstallDir(dir);
+    const result = await run([tool, "add", ...plan.packages], { cwd: dir, timeoutMs: INSTALL_TIMEOUT_MS });
+    if (result.code !== 0) throw failed(result, plan.packages.join(" "));
+    // bun can succeed and still leave nothing to run — a package that dropped its binary, or a
+    // name that now points somewhere else. Saying so beats a second "not installed".
+    if (!installedServerEntry(definition, dir)) {
+      throw new Error(`Installed ${plan.packages.join(" ")}, but it provides no ${definition.command}`);
+    }
+    return;
+  }
+
+  if (plan.with === "go") {
+    const binDir = path.join(dir, "bin");
+    mkdirSync(binDir, { recursive: true });
+    // `GOBIN` is the whole reason this lands in PPM's directory rather than `~/go/bin`. The
+    // module and build caches stay where the user's Go already keeps them — those are the
+    // toolchain's, and re-downloading the world into the PPM directory would be rude.
+    const result = await run([tool, "install", plan.module], {
+      cwd: dir,
+      env: { ...process.env, GOBIN: binDir },
+      timeoutMs: INSTALL_TIMEOUT_MS,
+    });
+    if (result.code !== 0) throw failed(result, plan.module);
+    const built = installedBinaryPath(definition, dir);
+    if (!built || !existsSync(built)) {
+      throw new Error(`Built ${plan.module}, but no ${definition.command} appeared in ${binDir}`);
+    }
+    return;
+  }
+
+  // rustup. Run where the project is, so a repository pinned to its own toolchain gets the
+  // component added to *that* one rather than to whichever is default.
+  const cwd = projectPath && existsSync(projectPath) ? projectPath : process.cwd();
+  const result = await run([tool, "component", "add", plan.component], { cwd, timeoutMs: INSTALL_TIMEOUT_MS });
+  if (result.code !== 0) throw failed(result, plan.component);
+  if (!(await rustupServerPath(definition, cwd, run))) {
+    throw new Error(`rustup reported success but still has no ${definition.command} for this toolchain`);
+  }
+}
+
+async function uninstall(definition: LanguageServerDefinition, projectPath: string | undefined, run: Runner): Promise<void> {
+  const plan = definition.install;
+  // Both of these are the route's job to prevent; they are here because this function deletes
+  // things, and "the caller checked" is not a property a deleting function should rely on.
+  if (!plan) throw new Error(`PPM did not install ${definition.displayName}, so there is nothing to remove.`);
+  const dir = lspInstallDir();
+
+  if (plan.with === "bun") {
+    if (!installedServerEntry(definition, dir)) {
+      throw new Error(`${definition.displayName} is not in PPM's own folder, so there is nothing for PPM to remove.`);
+    }
+    const tool = installToolPath(plan);
+    if (!tool) throw new Error(`bun is not installed on this host, so PPM cannot remove ${definition.displayName}.`);
+    // By name, never by the spec that installed it: `bun remove typescript@5` is not the same
+    // request as `bun remove typescript`, and the manifest holds the name.
+    const names = plan.packages.map(packageName);
+    const result = await run([tool, "remove", ...names], { cwd: dir, timeoutMs: INSTALL_TIMEOUT_MS });
+    if (result.code !== 0) throw new Error(`Could not remove ${names.join(" ")}: ${output(result)}`);
+    return;
+  }
+
+  if (plan.with === "go") {
+    const binary = installedBinaryPath(definition, dir);
+    if (!binary || !existsSync(binary)) {
+      throw new Error(`${definition.displayName} is not in PPM's own folder, so there is nothing for PPM to remove.`);
+    }
+    try {
+      rmSync(binary);
+    } catch (e) {
+      // Windows refuses to unlink a running executable, which is the one platform where an
+      // uninstall fails for a reason the user can act on.
+      throw new Error(`Could not delete ${binary}: ${(e as Error).message}`);
+    }
+    return;
+  }
+
+  // rustup, in the same directory the install would have used, so the component leaves the
+  // toolchain it was added to rather than whichever happens to be default.
+  const cwd = projectPath && existsSync(projectPath) ? projectPath : process.cwd();
+  const tool = installToolPath(plan);
+  if (!tool) throw new Error(`rustup is not installed on this host, so PPM cannot remove ${definition.displayName}.`);
+  const result = await run([tool, "component", "remove", plan.component], { cwd, timeoutMs: INSTALL_TIMEOUT_MS });
+  if (result.code !== 0) throw new Error(`Could not remove ${plan.component}: ${output(result)}`);
+}
+
+/** What a failed command said, bounded — a build log's last 400 characters hold the reason. */
+function output(result: RunResult): string {
+  return (result.stderr.trim() || result.stdout.trim()).slice(-400) || `exit ${result.code}`;
+}
+
+function ensureInstallDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+  const manifest = path.join(dir, "package.json");
+  if (!existsSync(manifest)) {
+    writeFileSync(manifest, `${JSON.stringify({ name: "ppm-lsp-servers", private: true, dependencies: {} }, null, 2)}\n`);
+  }
+}