@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10-10

package/src/bridges/reserved-dispatch.ts

@@ -1,5 +1,11 @@
 import type { AgentToolResult, EvalHandleHost } from "@code-yeongyu/senpi";
-import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL, RESERVED_SCHEMA_TOOL } from "../bridge/reserved.ts";
+import {
+	RESERVED_AGENT_TOOL,
+	RESERVED_OUTPUT_TOOL,
+	RESERVED_PACKAGES_INSTALL_TOOL,
+	RESERVED_SCHEMA_TOOL,
+} from "../bridge/reserved.ts";
+import { type PackagesInstallEnvironments, runPackagesInstall } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
 import { type AgentExecuteTool, runEvalAgent } from "./agent-bridge.ts";
@@ -21,6 +27,8 @@ export interface ReservedDispatchContext {
 	readonly handles?: HandleRegistry;
 	/** `ctx.evalHandleHost` at dispatch time; agent/workpool refs need it, completion refs do not. */
 	readonly evalHandleHost?: EvalHandleHost;
+	/** The calling cell's session environments; `packages.install()` fails with environment_installer_unavailable without one. */
+	readonly environments?: PackagesInstallEnvironments;
 }
 
 class SchemaUnavailableError extends Error {
@@ -36,6 +44,7 @@ export function isReservedToolName(toolName: string): boolean {
 		toolName === RESERVED_AGENT_TOOL ||
 		toolName === RESERVED_OUTPUT_TOOL ||
 		toolName === RESERVED_SCHEMA_TOOL ||
+		toolName === RESERVED_PACKAGES_INSTALL_TOOL ||
 		isHandleToolName(toolName)
 	);
 }
@@ -66,6 +75,9 @@ export async function runReservedTool(toolName: string, context: ReservedDispatc
 			marshalToolResult: context.marshalToolResult,
 		});
 	}
+	if (toolName === RESERVED_PACKAGES_INSTALL_TOOL) {
+		return await runPackagesInstall(context.args, context.environments ?? {}, context.signal);
+	}
 	if (toolName === RESERVED_SCHEMA_TOOL) {
 		const listTools = context.listTools;
 		if (listTools === undefined) throw new SchemaUnavailableError();

package/src/config/executable-settings.json

@@ -0,0 +1,5 @@
+{
+	"projectExecutableSettings": [
+		"languages.pyInterpreter"
+	]
+}

package/src/config/project-trust.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import executableSettings from "./executable-settings.json" with { type: "json" };
+import type { CodemodeSettings } from "./settings.ts";
+
+/**
+ * Settings that name an executable run at session start (an interpreter's `--version` probe, then the kernel). The
+ * one list of them lives in `executable-settings.json`, which senpi's project-trust check also reads: a project
+ * codemode file that sets any of them asks for trust. Without trust they are dropped with a warning and never run.
+ * Trust is asked only when the project's own file sets one, so a host that cannot answer still starts sessions;
+ * such a host counts as not trusting the project.
+ */
+export const PROJECT_EXECUTABLE_SETTINGS: readonly string[] = executableSettings.projectExecutableSettings;
+
+export function withoutUntrustedInterpreter<Settings extends CodemodeSettings>(
+	settings: Settings,
+	source: string | null,
+	cwd: string,
+	isProjectTrusted: (() => boolean) | undefined,
+): { readonly settings: Settings; readonly warning?: string } {
+	const projectFile = join(cwd, ".senpi", "codemode.json");
+	if (source !== projectFile) return { settings };
+	const named = PROJECT_EXECUTABLE_SETTINGS.filter((path) => valueAt(settings, path) !== undefined);
+	if (named.length === 0 || isProjectTrusted?.() === true) return { settings };
+	let trimmed: Settings = settings;
+	for (const path of named) trimmed = withoutPath(trimmed, path);
+	const list = named.map((path) => `${path} "${String(valueAt(settings, path))}"`).join(", ");
+	return {
+		settings: trimmed,
+		warning: `${list} in ${projectFile} is ignored because this project is not trusted; it was not run`,
+	};
+}
+
+function valueAt(value: unknown, path: string): unknown {
+	let current: unknown = value;
+	for (const key of path.split(".")) {
+		if (typeof current !== "object" || current === null) return undefined;
+		current = Reflect.get(current, key);
+	}
+	return current;
+}
+
+function withoutPath<T>(value: T, path: string): T {
+	const copy = structuredClone(value);
+	const keys = path.split(".");
+	const last = keys.pop();
+	let parent: unknown = copy;
+	for (const key of keys)
+		parent = typeof parent === "object" && parent !== null ? Reflect.get(parent, key) : undefined;
+	if (last !== undefined && typeof parent === "object" && parent !== null) Reflect.deleteProperty(parent, last);
+	return copy;
+}

package/src/config/settings-overrides.ts

@@ -20,6 +20,8 @@ export function resolveEnabledLanguages(
 	env: Environment = process.env,
 ): CodemodeSettings["languages"] {
 	return {
+		// Keep the non-flag keys (languages.pyInterpreter); only the four enable flags take env overrides.
+		...settings.languages,
 		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
 		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
 		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),

package/src/environments/js-environments.ts

@@ -0,0 +1,208 @@
+import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import { withRootLock } from "./install-lock.ts";
+import {
+	absoluteSpec,
+	type JsInstallerChoice,
+	parseJsPackages,
+	requestedPackageName,
+	resolveJsInstaller,
+	runJsInstall,
+	withoutHostPaths,
+} from "./js-installer.ts";
+import { carryNpmrcSettings, recordedFileSpecs, seedPackageJson } from "./js-revision-files.ts";
+import { assertBuiltRevisionLinks, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
+import { projectResolves } from "./project-resolves.ts";
+import type { EnvironmentMode } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import { mkdirPrivate, publishNextRevision, readActiveRevision } from "./revision-store.ts";
+
+/** The paths in a revision that the installer writes. */
+const INSTALLER_WRITES = [
+	"package.json",
+	"package-lock.json",
+	"bun.lock",
+	"bun.lockb",
+	"node_modules",
+	".npmrc",
+	"bunfig.toml",
+];
+
+export interface JsInstallReceipt {
+	readonly installer: "bun" | "npm";
+	readonly mode: EnvironmentMode;
+	readonly revision: number | undefined;
+	readonly added: readonly string[];
+	readonly shadowed: readonly string[];
+}
+
+export interface JsEnvironmentsOptions {
+	readonly artifactsDir: string;
+	readonly cwd: string;
+	readonly runtime: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly settings: Pick<ResolvedCodemodeSettings, "environments">;
+}
+
+export class JsEnvironments {
+	readonly #options: JsEnvironmentsOptions;
+	#mode: EnvironmentMode = "managed";
+	#packageRoot: string | undefined;
+
+	constructor(options: JsEnvironmentsOptions) {
+		this.#options = options;
+	}
+
+	get mode(): EnvironmentMode {
+		return this.#mode;
+	}
+
+	get packageRoot(): string | undefined {
+		return this.#mode === "managed" ? this.#packageRoot : undefined;
+	}
+
+	async setMode(mode: EnvironmentMode): Promise<string> {
+		this.#mode = mode;
+		if (mode === "project") return this.#options.cwd;
+		this.#packageRoot = (await readActiveRevision(this.#managedBase()))?.dir;
+		return this.#managedBase();
+	}
+
+	async install(
+		requested: string,
+		signal: AbortSignal,
+		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
+		requestedInstaller?: "bun" | "npm",
+	): Promise<JsInstallReceipt> {
+		const environments = this.#options.settings.environments;
+		if (environments?.autoProvision === false) {
+			throw new EnvironmentError(
+				"environment_installer_unavailable",
+				"installs are turned off for this project (environments.autoProvision is false)",
+			);
+		}
+		const packages = parseJsPackages(requested).map((spec) => absoluteSpec(spec, this.#options.cwd));
+		// `%bun add` and `%npm add` name their installer; the setting applies only where the magic does not.
+		const choice: JsInstallerChoice = requestedInstaller ?? environments?.js?.installer ?? "auto";
+		const { installer, command } = resolveJsInstaller(choice, this.#options.env);
+		let recordedSpecs: readonly string[] = [];
+		const run = (root: string, remove?: string) =>
+			runJsInstall({
+				installer,
+				command,
+				root,
+				packages,
+				...(remove === undefined ? {} : { remove }),
+				recordedSpecs,
+				cwd: this.#options.cwd,
+				env: this.#options.env,
+				signal,
+				...(onOutput === undefined ? {} : { onOutput }),
+			});
+		// The lock and the revision store fail with raw file system errors; they reach the cell redacted.
+		const redacted =
+			(...roots: string[]) =>
+			(error: unknown) => {
+				const raw =
+					error instanceof EnvironmentError
+						? error.message.slice(error.code.length + 2)
+						: String(error instanceof Error ? error.message : error);
+				const text = roots.reduce(
+					(message, root) => withoutHostPaths(message, { root, cwd: this.#options.cwd, packages, recordedSpecs }),
+					raw,
+				);
+				if (error instanceof EnvironmentError) throw new EnvironmentError(error.code, text);
+				// An abort while waiting for the lock or before the publish is a cancel, not a failure.
+				if (signal.aborted)
+					throw new EnvironmentError("environment_install_cancelled", `the install was cancelled: ${text}`);
+				throw new EnvironmentError("environment_install_failed", text);
+			};
+		if (this.#mode === "project") {
+			const before = await dependencyNames(this.#options.cwd);
+			const lockRoot = join(this.#options.cwd, ".senpi", "js-packages");
+			await mkdir(lockRoot, { recursive: true });
+			await withRootLock(lockRoot, async () => await run(this.#options.cwd), signal).catch(redacted(lockRoot));
+			const added = (await dependencyNames(this.#options.cwd)).filter((name) => !before.includes(name));
+			return { installer, mode: "project", revision: undefined, added, shadowed: [] };
+		}
+		let added: string[] = [];
+		const requestedBase = this.#managedBase();
+		const base = await canonicalBase(this.#managedRoot(), requestedBase).catch(redacted(requestedBase));
+		const { revision } = await publishNextRevision(
+			base,
+			async (staging) => {
+				await carryNpmrcSettings(staging);
+				await rm(join(staging, "bunfig.toml"), { recursive: true, force: true });
+				await seedPackageJson(staging);
+				// Every path the installer writes must be the revision's own, never a link out of it.
+				for (const entry of INSTALLER_WRITES) await assertNoLinksBelow(base, join(staging, entry));
+				const before = await dependencyNames(staging);
+				recordedSpecs = await recordedFileSpecs(staging);
+				// A package whose source changes kind (a directory to a tarball or registry version, or back) is removed
+				// first: bun keeps its per-file links into the old directory otherwise (#2758).
+				for (const name of await sourceKindChanges(staging, packages)) await run(staging, name);
+				await run(staging);
+				await assertBuiltRevisionLinks(staging);
+				added = (await dependencyNames(staging)).filter((name) => !before.includes(name));
+			},
+			signal,
+		).catch(redacted(base, requestedBase));
+		this.#packageRoot = revision.dir;
+		const shadowed = added.filter((name) => projectResolves(this.#options.cwd, name));
+		return { installer, mode: "managed", revision: revision.number, added, shadowed };
+	}
+
+	#managedRoot(): string {
+		return this.#options.settings.environments?.managedRoot ?? this.#options.artifactsDir;
+	}
+
+	#managedBase(): string {
+		return join(this.#managedRoot(), "environments", "js", this.#options.runtime);
+	}
+}
+
+async function dependencyNames(root: string): Promise<string[]> {
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return [];
+		const dependencies = manifest.dependencies;
+		return typeof dependencies === "object" && dependencies !== null ? Object.keys(dependencies) : [];
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/**
+ * Creates the managed base, checks that nothing below the managed root is a link, and returns its realpath: npm keys
+ * a linked package in its lockfile by a path relative to the prefix, and a prefix under a linked directory (macOS
+ * `/var` is a link to `/private/var`) gives keys that stop resolving once the staged revision is renamed.
+ */
+async function canonicalBase(managedRoot: string, base: string): Promise<string> {
+	await assertNoLinksBelow(managedRoot, base);
+	await mkdirPrivate(base);
+	await assertNoLinksBelow(managedRoot, base);
+	return await realpath(base);
+}
+
+/** Names among `packages` whose recorded source is a directory and is not the same directory now, or the reverse. */
+export async function sourceKindChanges(revision: string, packages: readonly string[]): Promise<string[]> {
+	const installed = new Set(await dependencyNames(revision));
+	const sources = await recordedInstallSources(revision);
+	const changed: string[] = [];
+	for (const spec of packages) {
+		const name = await requestedPackageName(spec);
+		if (name === undefined || !installed.has(name)) continue;
+		const directory = await localDirectory(spec);
+		if (directory !== sources.get(name)) changed.push(name);
+	}
+	return changed;
+}
+
+async function localDirectory(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (!isAbsolute(path)) return undefined;
+	const resolved = await realpath(path).catch(() => undefined);
+	return resolved !== undefined && (await stat(resolved)).isDirectory() ? resolved : undefined;
+}

package/src/environments/js-installer.ts

@@ -0,0 +1,268 @@
+import { execFile, spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, delimiter, isAbsolute, join, resolve, sep } from "node:path";
+import { EnvironmentError } from "./py-installer.ts";
+
+export type JsInstallerChoice = "auto" | "bun" | "npm";
+export type JsInstaller = "bun" | "npm";
+
+const STDERR_TAIL_BYTES = 4_096;
+
+function onPath(command: string, env: NodeJS.ProcessEnv): string | undefined {
+	const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+	const extensions = process.platform === "win32" ? [".exe", ".cmd", ""] : [""];
+	for (const directory of (env[pathKey] ?? "").split(delimiter)) {
+		if (directory === "") continue;
+		for (const extension of extensions) {
+			const candidate = join(directory, `${command}${extension}`);
+			if (existsSync(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+export function resolveJsInstaller(
+	choice: JsInstallerChoice,
+	env: NodeJS.ProcessEnv,
+): { readonly installer: JsInstaller; readonly command: string } {
+	const order: readonly JsInstaller[] = choice === "auto" ? ["bun", "npm"] : [choice];
+	for (const installer of order) {
+		const command = onPath(installer, env);
+		if (command !== undefined) return { installer, command };
+	}
+	throw new EnvironmentError(
+		"environment_installer_unavailable",
+		choice === "auto" ? "neither bun nor npm is on PATH" : `${choice} is not on PATH`,
+	);
+}
+
+export function parseJsPackages(text: string): string[] {
+	if (/[\u0000-\u0008\u000e-\u001f\u007f]/.test(text)) {
+		throw new EnvironmentError("environment_install_failed", "package names cannot contain control characters");
+	}
+	const packages = text.split(/\s+/).filter((token) => token !== "");
+	const flag = packages.find((token) => token.startsWith("-"));
+	if (flag !== undefined) {
+		throw new EnvironmentError(
+			"environment_install_failed",
+			`installer flags are chosen by the host; name packages only (got ${flag})`,
+		);
+	}
+	if (packages.length === 0)
+		throw new EnvironmentError("environment_install_failed", "name at least one package to add");
+	return packages;
+}
+
+/**
+ * A path-like spec (`./pkg`, `../x.tgz`, `file:./pkg`) means a path from the session directory; both installers get it
+ * absolute, because bun resolves a relative spec from the revision it builds and npm from its own cwd.
+ */
+export function absoluteSpec(spec: string, cwd: string): string {
+	const file = spec.startsWith("file:") ? spec.slice("file:".length) : undefined;
+	const path = file ?? spec;
+	const pathLike = path.startsWith("./") || path.startsWith("../") || path === "." || path === "..";
+	if (!pathLike) return spec;
+	const absolute = resolve(cwd, path);
+	return file === undefined ? absolute : `file:${absolute}`;
+}
+
+export function jsInstallArgv(installer: JsInstaller, root: string, packages: readonly string[]): string[] {
+	return installer === "bun"
+		? ["add", "--ignore-scripts", "--cwd", root, ...packages]
+		: ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--prefix", root, ...packages];
+}
+
+export function jsRemoveArgv(installer: JsInstaller, root: string, name: string): string[] {
+	return installer === "bun"
+		? ["remove", "--ignore-scripts", "--cwd", root, name]
+		: ["uninstall", "--ignore-scripts", "--no-audit", "--no-fund", "--prefix", root, name];
+}
+
+const REGISTRY_NAME = /^((?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*)(?:@[^/]*)?$/i;
+
+/**
+ * The package name a spec installs, when it can be known before the install: a local directory's or tarball's own
+ * `package.json` name, or the name of a registry spec (`name`, `name@range`, `@scope/name@range`). Undefined for URL
+ * and git specs.
+ */
+export async function requestedPackageName(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (isAbsolute(path)) {
+		try {
+			const manifest: unknown = JSON.parse(
+				(await stat(path)).isDirectory()
+					? await readFile(join(path, "package.json"), "utf8")
+					: await tarballManifest(path),
+			);
+			return typeof manifest === "object" &&
+				manifest !== null &&
+				"name" in manifest &&
+				typeof manifest.name === "string"
+				? manifest.name
+				: undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	return REGISTRY_NAME.exec(spec)?.[1];
+}
+
+/**
+ * An archive's own `package.json`, read from its single top-level directory as both installers unpack it: npm's
+ * `package/`, or a GitHub-style `<repo>-<sha>/`. tar detects the compression itself, so a plain `.tar` works too.
+ */
+async function tarballManifest(path: string): Promise<string> {
+	const entries = (await tarOutput(["-tf", path])).split("\n").filter((entry) => entry !== "");
+	const normalized = (entry: string) => entry.replace(/^(\.\/)+/, "");
+	const tops = new Set(entries.map((entry) => normalized(entry).split("/")[0] ?? "").filter((top) => top !== ""));
+	// An archive whose entries do not all sit under one directory has no single package to name: judging it by
+	// whichever entry comes first could name the wrong one.
+	const [top, ...others] = [...tops];
+	if (top === undefined || others.length > 0 || top === "." || top === "..") {
+		throw new Error("the archive does not hold one top-level directory");
+	}
+	// Extract by the member's own name: GNU tar matches it exactly, so a leading "./" must be kept.
+	const manifest = entries.find((entry) => normalized(entry) === `${top}/package.json`);
+	if (manifest === undefined) throw new Error("the archive holds no package.json in its top-level directory");
+	return await tarOutput(["-xOf", path, manifest]);
+}
+
+function tarOutput(args: readonly string[]): Promise<string> {
+	return new Promise((resolveText, reject) => {
+		execFile("tar", [...args], { maxBuffer: 64 << 20 }, (error, stdout) =>
+			error === null ? resolveText(stdout) : reject(error),
+		);
+	});
+}
+
+export function runJsInstall(input: {
+	readonly installer: JsInstaller;
+	readonly command: string;
+	readonly root: string;
+	readonly packages: readonly string[];
+	/** Remove this package instead of adding `packages`. */
+	readonly remove?: string;
+	/** Absolute specs already recorded in the revision; the installer echoes them, so they are redacted too. */
+	readonly recordedSpecs?: readonly string[];
+	readonly cwd: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly signal: AbortSignal;
+	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+}): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (input.signal.aborted) {
+			reject(new EnvironmentError("environment_install_cancelled", "the install was cancelled before it started"));
+			return;
+		}
+		const argv =
+			input.remove === undefined
+				? jsInstallArgv(input.installer, input.root, input.packages)
+				: jsRemoveArgv(input.installer, input.root, input.remove);
+		const child = spawn(input.command, argv, {
+			cwd: input.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			// npm reads `global`/`location` from any .npmrc and the env; a global install would land where the import never looks.
+			env: {
+				...input.env,
+				npm_config_ignore_scripts: "true",
+				npm_config_global: "false",
+				npm_config_location: "project",
+			},
+			detached: process.platform !== "win32",
+		});
+		let output = "";
+		const record = (stream: "stdout" | "stderr") => (data: string) => {
+			output = (output + data).slice(-STDERR_TAIL_BYTES);
+			input.onOutput?.(stream, withoutHostPaths(data, input));
+		};
+		child.stdout.setEncoding("utf8").on("data", record("stdout"));
+		child.stderr.setEncoding("utf8").on("data", record("stderr"));
+		const onAbort = () => {
+			if (child.pid !== undefined && process.platform !== "win32") {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+					return;
+				} catch {
+					// ESRCH (the group is gone) or EPERM (macOS refuses a group whose leader already exited): stop the
+					// installer itself. An abort listener must never throw: nothing above it can catch the error.
+				}
+			}
+			child.kill("SIGKILL");
+		};
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		child.once("error", (error) => {
+			input.signal.removeEventListener("abort", onAbort);
+			reject(
+				new EnvironmentError(
+					"environment_installer_unavailable",
+					`${input.installer}: ${withoutHostPaths(error.message, input)}`,
+				),
+			);
+		});
+		child.once("close", (code, signal) => {
+			input.signal.removeEventListener("abort", onAbort);
+			if (input.signal.aborted) {
+				reject(
+					new EnvironmentError(
+						"environment_install_cancelled",
+						`the install was cancelled${cancelReason(input.signal, input)}; ${input.installer} was stopped`,
+					),
+				);
+			} else if (code === 0) resolve();
+			else {
+				reject(
+					new EnvironmentError(
+						"environment_install_failed",
+						withoutHostPaths(output.trim(), input) || `${input.installer} exited with ${code ?? signal}`,
+					),
+				);
+			}
+		});
+	});
+}
+
+function cancelReason(signal: AbortSignal, input: Parameters<typeof withoutHostPaths>[1]): string {
+	const reason: unknown = signal.reason;
+	return reason instanceof Error && reason.name !== "AbortError" ? `: ${withoutHostPaths(reason.message, input)}` : "";
+}
+
+/** Installer output names the session's own roots; error text says `<root>`/`<cwd>`/`~` instead of absolute paths. */
+export function withoutHostPaths(
+	text: string,
+	input: {
+		readonly root: string;
+		readonly cwd: string;
+		readonly packages: readonly string[];
+		readonly recordedSpecs?: readonly string[];
+	},
+): string {
+	const home = homedir();
+	// A spec that is an absolute file path names the user's file system; it is shown by its file name only.
+	// This install's absolute specs, and every path an earlier install recorded (npm records a relative `file:` path).
+	const requested = input.packages
+		.map((spec) => (spec.startsWith("file:") ? spec.slice("file:".length) : spec))
+		.filter((path) => isAbsolute(path));
+	const specPaths = [...requested, ...(input.recordedSpecs ?? [])]
+		.sort((a, b) => b.length - a.length)
+		.map((path) => [path, `<path>/${basename(path)}`] as const);
+	return [
+		...specPaths,
+		[input.root, "<root>"],
+		[input.cwd, "<cwd>"],
+		[realpathOrSelf(tmpdir()), "<tmp>"],
+		[tmpdir(), "<tmp>"],
+		[home, "~"],
+	]
+		.filter(([path]) => path !== "" && path !== sep)
+		.reduce((current, [path, label]) => current.replaceAll(path, label), text);
+}
+
+function realpathOrSelf(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return path;
+	}
+}

package/src/environments/js-revision-files.ts

@@ -0,0 +1,91 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+
+const NPMRC_CARRIED_KEY = /^(?:registry|@[^\s=:/]+:registry|strict-ssl|ca|cafile)$/;
+
+/**
+ * A revision carries forward only the registry settings of its `.npmrc`: `registry`, `@scope:registry`, `strict-ssl`,
+ * `ca` and `cafile`. Every other key, credentials included, is dropped by default, and the file is rewritten as a
+ * regular file: a symlinked `.npmrc` is replaced, never written through, so the file it pointed at stays untouched.
+ */
+export async function carryNpmrcSettings(root: string): Promise<void> {
+	const path = join(root, ".npmrc");
+	let text: string;
+	try {
+		text = await readFile(path, "utf8");
+	} catch {
+		await rm(path, { recursive: true, force: true });
+		return;
+	}
+	const kept = text
+		.split(/\r\n|\r|\n/)
+		.map((line) => line.trim())
+		.filter((line) => {
+			const key = line.split("=", 1)[0]?.trim() ?? "";
+			return line.includes("=") && NPMRC_CARRIED_KEY.test(key);
+		})
+		.flatMap((line) => {
+			const carried = withoutUrlCredentials(line);
+			return carried === undefined ? [] : [carried];
+		});
+	await rm(path, { recursive: true, force: true });
+	if (kept.length > 0) await writeFile(path, `${kept.join("\n")}\n`, { mode: 0o600, flag: "wx" });
+}
+
+/**
+ * The `file:` and absolute path specs a revision's `package.json` already records, as written (npm writes a relative
+ * `file:../..` path) and resolved against the revision: the installer echoes them on every later install.
+ */
+export async function recordedFileSpecs(root: string): Promise<string[]> {
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return [];
+		const dependencies = manifest.dependencies;
+		if (typeof dependencies !== "object" || dependencies === null) return [];
+		return Object.values(dependencies).flatMap((spec) => {
+			if (typeof spec !== "string") return [];
+			if (spec.startsWith("file:")) {
+				const path = spec.slice("file:".length);
+				return isAbsolute(path) ? [path] : [path, resolve(root, path)];
+			}
+			return isAbsolute(spec) ? [spec] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * A carried `registry`/`@scope:registry` value keeps only its scheme, host and path: user info, a query and a fragment
+ * can each carry a credential, so they are cleared with the WHATWG URL parser npm itself uses. The path is kept, since
+ * registries are addressed by it, so a registry that embeds a token in its path keeps it in the revision's private
+ * (0600, in a 0700 directory) copy. A value that does not parse is dropped, and so is one that names an environment
+ * variable (`${...}`): npm expands it at install time, and a parsed copy would be a different URL. Other carried keys
+ * pass unchanged.
+ */
+function withoutUrlCredentials(line: string): string | undefined {
+	const separator = line.indexOf("=");
+	const key = line.slice(0, separator).trim();
+	if (!key.endsWith("registry")) return line;
+	const raw = line.slice(separator + 1).trim();
+	if (raw.includes("${")) return undefined;
+	const quote = raw.length >= 2 && (raw[0] === '"' || raw[0] === "'") && raw.endsWith(raw[0]) ? raw[0] : "";
+	let url: URL;
+	try {
+		url = new URL(quote === "" ? raw : raw.slice(1, -1));
+	} catch {
+		return undefined;
+	}
+	url.username = "";
+	url.password = "";
+	url.search = "";
+	url.hash = "";
+	return `${key}=${quote}${url.href}${quote}`;
+}
+
+/** Without its own `package.json`, bun walks up from the revision and installs into the nearest one above it. */
+export async function seedPackageJson(root: string): Promise<void> {
+	await writeFile(join(root, "package.json"), '{"private":true}\n', { flag: "wx" }).catch((error: unknown) => {
+		if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+	});
+}