@jxsuite/server 6.1.0 → 8.0.0

package/src/npm-path.ts

@@ -0,0 +1,145 @@
+/**
+ * Resolving an npm bare specifier from a URL path, shared by the dev server (`server.ts`) and the
+ * desktop's project server (`project-server.ts`). Its own module so the project server does not
+ * import the dev server, which stays Bun-only (server.md §1).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/**
+ * Read `key` off a parsed `package.json` value, or `undefined` when the value is not an object.
+ *
+ * Every lookup below reads through this one, so a manifest of the wrong shape (an `exports` that is
+ * a string, a `main` that is an array) yields "absent" rather than a member of something else.
+ */
+function manifestField(value: JsonValue | undefined, key: string): JsonValue | undefined {
+  return isJsonObject(value) ? value[key] : undefined;
+}
+
+/** Read and parse a package's `package.json`. Throws when the file is not JSON. */
+function readManifest(pkgJsonPath: string): JsonValue {
+  // SAFETY: JSON.parse without a reviver only ever yields a JSON value; its `any` says no more.
+  return JSON.parse(readFileSync(pkgJsonPath, "utf8")) as JsonValue;
+}
+
+/**
+ * Resolve an npm-style bare specifier from a URL path via node_modules. Handles scoped packages
+ * (@scope/pkg/subpath) and respects package.json exports. Strips leading directory segments (e.g.
+ * /pages/@scope/pkg/file → @scope/pkg/file).
+ *
+ * @param {string} root - Absolute project root
+ * @param {string} urlPath - URL pathname (e.g. "/pages/@jxsuite/parser/Foo.class.json")
+ * @returns {string | null} Absolute file path or null
+ */
+export function resolveNpmPath(rootDir: string, urlPath: string): string | null {
+  let root = rootDir;
+  let segments = urlPath.split("/").filter(Boolean);
+
+  // If "node_modules" appears in the path, use everything before it as a subdirectory
+  // Prefix and everything after as the package specifier.
+  // E.g. /examples/demo/node_modules/@scope/pkg → root=root/examples/demo, pkg=@scope/pkg
+  const nmIdx = segments.indexOf("node_modules");
+  if (nmIdx !== -1) {
+    if (nmIdx > 0) {
+      root = join(root, ...segments.slice(0, nmIdx));
+    }
+    segments = segments.slice(nmIdx + 1);
+  }
+
+  // Find the package start — either @scope/pkg or unscoped pkg
+  let start = -1;
+  let isScoped = false;
+  for (let i = 0; i < segments.length; i++) {
+    if (segments[i]!.startsWith("@")) {
+      start = i;
+      isScoped = true;
+      break;
+    }
+  }
+
+  let pkgDir = "";
+  let subpath = "";
+
+  if (isScoped) {
+    if (start < 0 || start + 1 >= segments.length) {
+      return null;
+    }
+    const scope = segments[start]!;
+    const pkg = segments[start + 1]!;
+    subpath = segments.slice(start + 2).join("/");
+    pkgDir = join(root, "node_modules", scope, pkg);
+  } else {
+    // Unscoped: try each segment as a package name in node_modules
+    for (let i = 0; i < segments.length; i++) {
+      const candidate = join(root, "node_modules", segments[i]!);
+      if (existsSync(join(candidate, "package.json"))) {
+        start = i;
+        pkgDir = candidate;
+        subpath = segments.slice(i + 1).join("/");
+        break;
+      }
+    }
+    if (start < 0) {
+      return null;
+    }
+  }
+
+  const pkgJsonPath = join(pkgDir, "package.json");
+  if (!existsSync(pkgJsonPath)) {
+    return null;
+  }
+
+  // If there's a subpath, check package.json exports first
+  if (subpath) {
+    try {
+      const pkgJson = readManifest(pkgJsonPath);
+      const exportVal = manifestField(manifestField(pkgJson, "exports"), `./${subpath}`);
+      if (isString(exportVal)) {
+        const mapped = join(pkgDir, exportVal);
+        if (existsSync(mapped)) {
+          return mapped;
+        }
+      }
+    } catch {}
+    // Fall back to direct path
+    const direct = join(pkgDir, subpath);
+    if (existsSync(direct)) {
+      return direct;
+    }
+    // CEM-relative: subpath may be relative to the custom elements manifest directory
+    try {
+      const customElements = manifestField(readManifest(pkgJsonPath), "customElements");
+      if (isString(customElements) && customElements) {
+        const cemDir = customElements.replace(/\/[^/]+$/, "");
+        const cemRelative = join(pkgDir, cemDir, subpath);
+        if (existsSync(cemRelative)) {
+          return cemRelative;
+        }
+      }
+    } catch {}
+  }
+
+  // Bare package (no subpath): resolve entry point
+  try {
+    const pkgJson = readManifest(pkgJsonPath);
+    const exp = manifestField(manifestField(pkgJson, "exports"), ".");
+    // An explicit `null` entry declines the package's entry point outright: no `module`/`main`.
+    if (exp !== null) {
+      const conditional = isNonNullObject(exp)
+        ? (manifestField(exp, "import") ?? manifestField(exp, "default"))
+        : exp;
+      const entry =
+        conditional ?? manifestField(pkgJson, "module") ?? manifestField(pkgJson, "main");
+      if (isString(entry) && entry) {
+        const resolved = join(pkgDir, entry);
+        if (existsSync(resolved)) {
+          return resolved;
+        }
+      }
+    }
+  } catch {}
+
+  return null;
+}

package/src/packages-service.ts

@@ -0,0 +1,212 @@
+/**
+ * The cloud's package service: the operations of `packages.ts`, run lockfile-only over files a
+ * request carries, so a host with no filesystem of its own (the cloud's working tree lives in a
+ * Durable Object) gets the same `package.json` and `package-lock.json` a desktop install writes.
+ *
+ * Stateless. Each request's files are written into a fresh temporary directory, the operation runs
+ * there with `lockfileOnly` (no `node_modules`, no tarball downloaded, no install script), the two
+ * files are read back, and the directory is removed whatever happened. The reply says which of the
+ * request's files the operation deleted (`bun.lock`, on the first install), so the caller can apply
+ * the whole result to its own tree as one change, or nothing when `result.ok` is false.
+ *
+ * The request is refused (400) for any operation but add, remove and set-versions, and any file but
+ * the three below, before anything is written. It is meant to be reachable only from the host that
+ * owns the working tree (a container binding, not a public route), and it reads nothing but the
+ * public registry.
+ *
+ * @docs studio/projects/dependencies
+ */
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isBoolean, isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
+import type { PackageInfo, PackageOpResult } from "@jxsuite/protocol";
+import { addPackage, removePackage, setPackageVersions } from "./packages.ts";
+import type { PackageOpOptions } from "./packages.ts";
+import { serve } from "#serve";
+import type { ServeServer } from "./serve.ts";
+
+/** The files a request may carry, and the only ones a reply returns or reports deleted. */
+export const SERVICE_FILES = ["package.json", "package-lock.json", "bun.lock"] as const;
+
+const SERVICE_FILE_NAMES = new Set<string>(SERVICE_FILES);
+
+/** One of {@link SERVICE_FILES}. */
+export type ServiceFile = (typeof SERVICE_FILES)[number];
+
+/** A validated request. */
+export type ServiceOp =
+  | { op: "add"; spec: string; dev: boolean }
+  | { op: "remove"; name: string }
+  | { op: "set-versions"; updates: PackageInfo[] };
+
+/** What the service answers for an operation it ran. */
+export interface ServiceReply {
+  result: PackageOpResult;
+  /** The files as the operation left them; on failure, the request's files unchanged. */
+  files: Partial<Record<ServiceFile, string>>;
+  /** Request files the operation removed. */
+  deleted: ServiceFile[];
+}
+
+/** The largest request body accepted, in bytes: a lockfile is large, but not this large. */
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+/** True when `name` is one of {@link SERVICE_FILES}. */
+function isServiceFile(name: string): name is ServiceFile {
+  return SERVICE_FILE_NAMES.has(name);
+}
+
+/** A version update read off the request, or null when one member has the wrong shape. */
+function parseUpdate(value: JsonValue): PackageInfo | null {
+  if (!isJsonObject(value) || !isString(value.name) || !isString(value.version)) {
+    return null;
+  }
+  const update: PackageInfo = { name: value.name, version: value.version };
+  if (value.dev !== undefined) {
+    if (!isBoolean(value.dev)) {
+      return null;
+    }
+    update.dev = value.dev;
+  }
+  return update;
+}
+
+/** The operation a request names, or the reason it is refused. */
+export function parseOp(body: JsonObject): ServiceOp | { error: string } {
+  const { args } = body;
+  if (!isJsonObject(args)) {
+    return { error: "`args` must be an object" };
+  }
+  switch (body.op) {
+    case "add": {
+      if (!isString(args.spec) || (args.dev !== undefined && !isBoolean(args.dev))) {
+        return { error: "add takes { spec: string, dev?: boolean }" };
+      }
+      return { dev: args.dev === true, op: "add", spec: args.spec };
+    }
+    case "remove": {
+      return isString(args.name)
+        ? { name: args.name, op: "remove" }
+        : { error: "remove takes { name: string }" };
+    }
+    case "set-versions": {
+      const updates = Array.isArray(args.updates) ? args.updates.map(parseUpdate) : null;
+      if (!updates || updates.includes(null)) {
+        return { error: "set-versions takes { updates: { name, version, dev? }[] }" };
+      }
+      return { op: "set-versions", updates: updates.filter((update) => update !== null) };
+    }
+    default: {
+      return { error: "op must be add, remove or set-versions" };
+    }
+  }
+}
+
+/** The request's files, or the reason they are refused. */
+export function parseFiles(
+  value: JsonValue | undefined,
+): Map<ServiceFile, string> | { error: string } {
+  if (!isJsonObject(value)) {
+    return { error: "`files` must be an object" };
+  }
+  const files = new Map<ServiceFile, string>();
+  for (const [name, contents] of Object.entries(value)) {
+    if (!isServiceFile(name)) {
+      return { error: `${name} is not a file this service reads` };
+    }
+    if (!isString(contents)) {
+      return { error: `${name} must be a string` };
+    }
+    files.set(name, contents);
+  }
+  if (!files.has("package.json")) {
+    return { error: "package.json is required" };
+  }
+  return files;
+}
+
+/** Run `op` over `files` in a scratch directory and report what it left. */
+export async function runServiceOp(
+  op: ServiceOp,
+  files: Map<ServiceFile, string>,
+  options: Omit<PackageOpOptions, "lockfileOnly"> = {},
+): Promise<ServiceReply> {
+  const dir = await mkdtemp(join(tmpdir(), "jx-packages-service-"));
+  try {
+    for (const [name, contents] of files) {
+      await writeFile(join(dir, name), contents, "utf8");
+    }
+    const opOptions: PackageOpOptions = { ...options, lockfileOnly: true };
+    let result: PackageOpResult;
+    if (op.op === "add") {
+      result = await addPackage(dir, op.spec, op.dev, opOptions);
+    } else if (op.op === "remove") {
+      result = await removePackage(dir, op.name, opOptions);
+    } else {
+      result = await setPackageVersions(dir, op.updates, opOptions);
+    }
+    const out: ServiceReply["files"] = {};
+    const deleted: ServiceFile[] = [];
+    for (const name of SERVICE_FILES) {
+      const contents = await readFile(join(dir, name), "utf8").catch(() => null);
+      if (contents !== null) {
+        out[name] = contents;
+      } else if (files.has(name)) {
+        deleted.push(name);
+      }
+    }
+    return { deleted, files: out, result };
+  } finally {
+    await rm(dir, { force: true, recursive: true });
+  }
+}
+
+/**
+ * The service's fetch handler: `POST /` with `{ op, args, files }`, answered with a
+ * {@link ServiceReply}, or 400 for a request it refuses. `GET /health` answers 200.
+ */
+export async function handlePackagesRequest(
+  req: Request,
+  options: Omit<PackageOpOptions, "lockfileOnly"> = {},
+): Promise<Response> {
+  const { pathname } = new URL(req.url);
+  if (req.method === "GET" && pathname === "/health") {
+    return Response.json({ ok: true });
+  }
+  if (req.method !== "POST" || pathname !== "/") {
+    return Response.json({ error: "Not found" }, { status: 404 });
+  }
+  const length = Number(req.headers.get("content-length") ?? "0");
+  if (length > MAX_BODY_BYTES) {
+    return Response.json({ error: "Request too large" }, { status: 413 });
+  }
+  let body: JsonValue;
+  try {
+    // SAFETY: JSON.parse yields a JSON value; its shape is checked member by member below.
+    body = JSON.parse(await req.text()) as JsonValue;
+  } catch {
+    return Response.json({ error: "Body must be JSON" }, { status: 400 });
+  }
+  if (!isJsonObject(body)) {
+    return Response.json({ error: "Body must be an object" }, { status: 400 });
+  }
+  const op = parseOp(body);
+  if ("error" in op) {
+    return Response.json({ error: op.error }, { status: 400 });
+  }
+  const files = parseFiles(body.files);
+  if ("error" in files) {
+    return Response.json({ error: files.error }, { status: 400 });
+  }
+  return Response.json(await runServiceOp(op, files, options));
+}
+
+/** Start the service on `port` (all interfaces: it runs inside a container). */
+export function startPackagesService(
+  port: number,
+  hostname = "0.0.0.0",
+): Promise<ServeServer<undefined>> {
+  return serve({ fetch: (req) => handlePackagesRequest(req), hostname, port });
+}

package/src/packages.ts

@@ -1,13 +1,23 @@
 /**
- * Bun-driven package operations, parameterized by a project root. Shared by the desktop app
- * (`createPackageOps`) and the dev server's `/__studio/packages*` endpoints so both backends behave
- * identically. Every function is pure with respect to its `root` argument and spawns `bun` in that
- * directory.
+ * Package operations, parameterized by a project root: npm's own installer (`@npmcli/arborist`) run
+ * in-process. Shared by the desktop app (`createPackageOps`), the dev server's
+ * `/__studio/packages*` endpoints and the cloud's lockfile service (`packages-service.ts`), so
+ * every backend installs the same way and writes the same `package-lock.json` (server.md §4.1).
+ *
+ * Strict, on purpose: install scripts never run, a peer conflict fails rather than being forced, a
+ * spec that is not a registry package is refused, and a failed operation leaves `package.json` and
+ * the lockfile byte-identical. The public registry is the only one: a project `.npmrc` is not read,
+ * so a private scope fails with an error that names the registry and the status.
+ *
+ * @docs studio/projects/dependencies
  */
 
 import { existsSync } from "node:fs";
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, rm, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import Arborist from "@npmcli/arborist";
+import npa from "npm-package-arg";
+import { isNumber, isString } from "@jxsuite/schema/guards";
 import type { PackageInfo, PackageOpResult, PackageVersionInfo } from "@jxsuite/protocol";
 import type { JsonValue } from "@jxsuite/schema/types";
 
@@ -86,48 +96,232 @@ export function dependenciesNeedInstall(root: string): boolean {
   return !existsSync(resolve(root, "node_modules"));
 }
 
+/** The registry every operation resolves against; a project `.npmrc` is not read (see below). */
+export const NPM_REGISTRY = "https://registry.npmjs.org/";
+
 /**
- * Path to the bun executable. Uses the bun running the current process (`process.execPath`) so a
- * packaged desktop app spawns the bun bundled with its Electron distribution rather than relying on
- * a system-wide `bun` in `$PATH` (which end users may not have). Falls back to a PATH lookup if
- * `execPath` is somehow unset.
+ * How an operation runs. `lockfileOnly` resolves and writes `package.json` and `package-lock.json`
+ * without building `node_modules` or downloading a tarball: what the cloud service runs, where no
+ * `node_modules` exists and no package code may arrive. `registry` and `cache` exist for the tests'
+ * fixture registry and scratch cache; production callers leave them alone, which means the public
+ * registry and npm's own cache directory (`~/.npm/_cacache`, inside the sandbox container on the
+ * Mac App Store build).
  */
-export function bunExecutable(): string {
-  return process.execPath || "bun";
+export interface PackageOpOptions {
+  cache?: string;
+  lockfileOnly?: boolean;
+  registry?: string;
+}
+
+/** The files an operation may rewrite, restored byte-for-byte when it fails. */
+const GUARDED_FILES = ["package.json", "package-lock.json", "bun.lock"] as const;
+
+/** One project's operations, run one after another: two reifies in one tree race on its files. */
+const queues = new Map<string, Promise<PackageOpResult>>();
+
+/**
+ * Run `task` after every operation already queued for `root`, whether that one succeeded or not.
+ * `reify` turns every failure it can into a result, but a restore that itself fails still rejects,
+ * and the next operation must run regardless.
+ */
+function enqueue(root: string, task: () => Promise<PackageOpResult>): Promise<PackageOpResult> {
+  const previous = queues.get(root) ?? Promise.resolve();
+  const next = previous.then(task, task);
+  queues.set(root, next);
+  const forget = (): void => {
+    if (queues.get(root) === next) {
+      queues.delete(root);
+    }
+  };
+  void next.then(forget, forget);
+  return next;
+}
+
+/** The guarded files' current bytes (null for an absent file). */
+async function snapshot(root: string): Promise<Map<string, Buffer | null>> {
+  const saved = new Map<string, Buffer | null>();
+  for (const name of GUARDED_FILES) {
+    const path = resolve(root, name);
+    saved.set(name, existsSync(path) ? await readFile(path) : null);
+  }
+  return saved;
+}
+
+/** Put the guarded files back exactly as {@link snapshot} found them. */
+async function restore(root: string, saved: Map<string, Buffer | null>): Promise<void> {
+  for (const [name, bytes] of saved) {
+    const path = resolve(root, name);
+    await (bytes === null ? rm(path, { force: true }) : writeFile(path, bytes));
+  }
+}
+
+/** An error as npm's fetch and resolver raise them: a code, and for HTTP a status and a URL. */
+interface NpmError {
+  code?: string;
+  statusCode?: number;
+  uri?: string;
+  pkgid?: string;
+  message: string;
 }
 
-async function runBun(args: string[], cwd: string): Promise<PackageOpResult> {
-  const proc = Bun.spawn([bunExecutable(), ...args], { cwd, stderr: "pipe", stdout: "pipe" });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  const log = `${stdout}${stderr}`.trim();
-  const result: PackageOpResult = { ok: exitCode === 0 };
-  if (log) {
-    result.log = log;
+/** Read the fields {@link describeFailure} reports off whatever an operation threw. */
+function asNpmError(error: Error): NpmError {
+  const out: NpmError = { message: error.message };
+  if ("code" in error && isString(error.code)) {
+    out.code = error.code;
+  }
+  if ("statusCode" in error && isNumber(error.statusCode)) {
+    out.statusCode = error.statusCode;
+  }
+  if ("uri" in error && isString(error.uri)) {
+    out.uri = error.uri;
+  }
+  if ("pkgid" in error && isString(error.pkgid)) {
+    out.pkgid = error.pkgid;
+  }
+  return out;
+}
+
+/**
+ * The first line of a failed operation's log: what failed, in the terms the user can act on.
+ *
+ * A registry refusal names the package, the registry and the status, because the usual cause is a
+ * private scope or a mirror this installer does not read (`.npmrc` is not consulted). A peer
+ * conflict is reported as one, never forced through.
+ */
+function describeFailure(error: NpmError, registry: string): string {
+  if (error.statusCode !== undefined) {
+    const what = error.pkgid ?? error.uri ?? "a package";
+    return `The registry ${registry} answered ${error.statusCode} for ${what}. Private registries and .npmrc settings are not supported; install it from a terminal.`;
+  }
+  if (error.code === "ERESOLVE") {
+    return `The dependencies conflict (ERESOLVE): ${error.message}`;
+  }
+  if (error.code === "EUNSUPPORTEDPROTOCOL") {
+    return `A dependency uses a specifier this installer does not support: ${error.message}`;
   }
-  return result;
+  return error.code ? `${error.code}: ${error.message}` : error.message;
 }
 
-/** Run `bun install` in the project root. */
-export async function installDependencies(root: string): Promise<PackageOpResult> {
-  return runBun(["install"], root);
+/**
+ * Run one Arborist reify for `root` under the queue, the snapshot and the `bun.lock` switch.
+ *
+ * Strict by construction: no `force`, no `legacyPeerDeps`, scripts never run, and nothing is left
+ * half-done. On failure the manifest and lockfiles are restored byte-for-byte (Arborist rolls
+ * `node_modules` back itself). On success a project that had only a `bun.lock` loses it, because
+ * `package-lock.json` is now the lockfile and two lockfiles drift.
+ */
+function reify(
+  root: string,
+  options: PackageOpOptions,
+  prepare: () => Promise<Partial<ReifyOptions>>,
+): Promise<PackageOpResult> {
+  return enqueue(root, async () => {
+    const registry = options.registry ?? NPM_REGISTRY;
+    const hadBunLockOnly =
+      existsSync(resolve(root, "bun.lock")) && !existsSync(resolve(root, "package-lock.json"));
+    let saved: Map<string, Buffer | null> | null = null;
+    const lines: string[] = [];
+    const onLog = (level: string, ...args: unknown[]): void => {
+      if (level === "warn" || level === "error" || level === "notice") {
+        lines.push(args.map(String).join(" "));
+      }
+    };
+    process.on("log", onLog);
+    try {
+      saved = await snapshot(root);
+      const extra = await prepare();
+      const arboristOptions: ConstructorParameters<typeof Arborist>[0] = {
+        audit: false,
+        fund: false,
+        ignoreScripts: true,
+        lockfileVersion: 3,
+        packageLockOnly: options.lockfileOnly === true,
+        path: root,
+        registry,
+        save: true,
+      };
+      if (options.cache !== undefined) {
+        arboristOptions.cache = options.cache;
+      }
+      const arborist = new Arborist(arboristOptions);
+      await arborist.reify({ ...extra, save: true });
+      if (hadBunLockOnly) {
+        await rm(resolve(root, "bun.lock"), { force: true });
+        lines.push("Replaced bun.lock with package-lock.json, which Studio installs from.");
+      }
+      const result: PackageOpResult = { ok: true };
+      if (lines.length > 0) {
+        result.log = lines.join("\n");
+      }
+      return result;
+    } catch (error) {
+      if (saved) {
+        await restore(root, saved);
+      }
+      const npmError = asNpmError(error instanceof Error ? error : new Error(String(error)));
+      return { log: [describeFailure(npmError, registry), ...lines].join("\n"), ok: false };
+    } finally {
+      process.off("log", onLog);
+    }
+  });
+}
+
+/** What `reify` accepts beyond the constructor's options. */
+type ReifyOptions = NonNullable<Parameters<Arborist["reify"]>[0]>;
+
+/** Install the dependencies `package.json` declares, writing `package-lock.json`. */
+export function installDependencies(
+  root: string,
+  options: PackageOpOptions = {},
+): Promise<PackageOpResult> {
+  return reify(root, options, async () => ({}));
 }
 
-/** Run `bun add` (with `-d` for a dev dependency). */
+/**
+ * A registry spec (`name`, `name@1.2.3`, `name@^1`, `name@latest`), or the reason it is refused.
+ * Git, file, URL, alias and `workspace:` specs are refused before Arborist sees them.
+ */
+function registrySpec(spec: string): { ok: true; name: string } | { ok: false; reason: string } {
+  let parsed: ReturnType<typeof npa>;
+  try {
+    parsed = npa(spec);
+  } catch (error) {
+    return { ok: false, reason: `"${spec}" is not a registry package: ${String(error)}` };
+  }
+  if (!REGISTRY_SPEC_TYPES.has(parsed.type) || !parsed.name) {
+    return {
+      ok: false,
+      reason: `"${spec}" is a ${parsed.type} specifier; only packages from the registry can be added.`,
+    };
+  }
+  return { name: parsed.name, ok: true };
+}
+
+/** The `npm-package-arg` types that name a package on the registry. */
+const REGISTRY_SPEC_TYPES = new Set(["version", "range", "tag"]);
+
+/** Add a dependency (a devDependency when `dev`), saving `^<resolved>` as npm does. */
 export async function addPackage(
   root: string,
-  name: string,
+  spec: string,
   dev = false,
+  options: PackageOpOptions = {},
 ): Promise<PackageOpResult> {
-  return runBun(dev ? ["add", "-d", name] : ["add", name], root);
+  const checked = registrySpec(spec);
+  if (!checked.ok) {
+    return { log: checked.reason, ok: false };
+  }
+  return reify(root, options, async () => ({ add: [spec], saveType: dev ? "dev" : "prod" }));
 }
 
-/** Run `bun remove`. */
-export async function removePackage(root: string, name: string): Promise<PackageOpResult> {
-  return runBun(["remove", name], root);
+/** Remove a dependency from whichever section holds it. */
+export async function removePackage(
+  root: string,
+  name: string,
+  options: PackageOpOptions = {},
+): Promise<PackageOpResult> {
+  return reify(root, options, async () => ({ rm: [name] }));
 }
 
 /**
@@ -203,11 +397,12 @@ export async function packageVersions(
 /**
  * Rewrite the version range of each named package in whichever section it already occupies
  * (preserving dependencies/devDependencies placement; new names default to the caller's `dev`
- * flag), then run a single `bun install`.
+ * flag), then install once. A failed install leaves `package.json` as it was.
  */
 export async function setPackageVersions(
   root: string,
   updates: { name: string; version: string; dev?: boolean }[],
+  options: PackageOpOptions = {},
 ): Promise<PackageOpResult> {
   if (updates.length === 0) {
     return { ok: true };
@@ -233,6 +428,9 @@ export async function setPackageVersions(
       pkg[bucket] = { ...pkg[bucket], [update.name]: update.version };
     }
   }
-  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
-  return installDependencies(root);
+  // Written inside the operation, so the snapshot it restores on failure is the manifest before.
+  return reify(root, options, async () => {
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+    return {};
+  });
 }