@sparkelf/dsh-plus 0.1.0-rc.9 → 0.2.0-rc.2

package/lib/bin.js

@@ -1,10 +1,1037 @@
 #!/usr/bin/env node
-import { runApply } from "./apply.js";
+import { r as runApply } from "./apply-e0aMC4B4.js";
+import { createRequire } from "node:module";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, posix, resolve, win32 } from "node:path";
+import { homedir } from "node:os";
+import semver from "semver";
+import { parseDocument } from "yaml";
+import { fileURLToPath } from "node:url";
+import { createServer } from "node:net";
+//#region lib/types/registry-versions.js
+/**
+* Registry queries behind the `update` command.
+*
+* A standalone installation pins one exact distribution version, so it needs two
+* facts npm's own updater cannot give it: which versions exist, and which of them is
+* newer than the one installed. `pnpm update` treats an exact pin as a range of one
+* and always reports "already up to date".
+*/
+/** Every published version of one package, oldest first, with publication times. */
+function publishedVersions(name, registry = "https://registry.npmjs.org") {
+	let raw;
+	try {
+		raw = execFileSync("npm", [
+			"view",
+			name,
+			"time",
+			"--json",
+			"--registry",
+			registry
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+	} catch {
+		return [];
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return [];
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return [];
+	const times = parsed;
+	const entries = [];
+	for (const [version, time] of Object.entries(times)) {
+		if (version === "created" || version === "modified") continue;
+		if (semver.valid(version) === null) continue;
+		entries.push(typeof time === "string" ? {
+			version,
+			publishedAt: time
+		} : { version });
+	}
+	return entries.sort((left, right) => semver.compare(left.version, right.version));
+}
+/**
+* The highest published version that is newer than the installed one.
+*
+* Prerelease ordering matters here: an installation on a release candidate must not
+* be told that an older stable release is an upgrade, and must be told about a newer
+* candidate.
+*
+* @param name - package to query.
+* @param installed - version currently installed.
+* @param registry - registry to query.
+* @returns the newer version, or undefined when the installation is current.
+*/
+function newerVersion(name, installed, registry = "https://registry.npmjs.org") {
+	return publishedVersions(name, registry).filter((entry) => semver.gt(entry.version, installed)).at(-1);
+}
+//#endregion
+//#region lib/types/standalone-server.js
+/**
+* Process lifecycle for one standalone Plus server.
+*
+* A standalone user starts a server and later stops it, so the process outlives the
+* command that started it. This module owns the state that makes that possible: a
+* pid file beside the profile, an availability probe for the port, and the port
+* search that keeps a second instance usable without asking the user to pick one.
+*/
+/** Default port a standalone server binds when the user names none. */
+const DEFAULT_PORT = 3080;
+/** Milliseconds to wait for a stopped server to exit before forcing it. */
+const STOP_GRACE_MILLISECONDS = 1e4;
+/** Where one installation keeps its runtime state. */
+function stateDirectory(home) {
+	return join(home, "standalone");
+}
+function statePath(home) {
+	return join(stateDirectory(home), "server.json");
+}
+/** Whether a process with this id exists and is signalable. */
+function isRunning(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Read the recorded server state, or undefined when absent or its process is gone. */
+function readState(home) {
+	const path = statePath(home);
+	if (!existsSync(path)) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+	const record = parsed;
+	const pid = record.pid;
+	const port = record.port;
+	const url = record.url;
+	if (typeof pid !== "number" || typeof port !== "number" || typeof url !== "string") return void 0;
+	if (!isRunning(pid)) return void 0;
+	return {
+		pid,
+		port,
+		url
+	};
+}
+/** Record the running server, replacing any previous record. */
+function writeState(home, state) {
+	mkdirSync(stateDirectory(home), { recursive: true });
+	writeFileSync(statePath(home), JSON.stringify(state, null, 2) + "\n");
+}
+/** Remove the recorded state, whether or not a process still matches it. */
+function clearState(home) {
+	rmSync(statePath(home), { force: true });
+}
+/** Whether a TCP port on the loopback interface can be bound. */
+function portAvailable(port, host = "127.0.0.1") {
+	return new Promise((resolveAvailability) => {
+		const probe = createServer();
+		probe.once("error", () => {
+			resolveAvailability(false);
+		});
+		probe.once("listening", () => {
+			probe.close(() => {
+				resolveAvailability(true);
+			});
+		});
+		probe.listen(port, host);
+	});
+}
+/**
+* The first free port at or after `preferred`, so one occupied port never blocks a
+* start the way a bare bind failure would.
+*
+* @param preferred - port the user asked for, or the default.
+* @returns the chosen port, or undefined when the whole search window is occupied.
+*/
+async function choosePort(preferred, host = "127.0.0.1") {
+	for (let offset = 0; offset < 10; offset += 1) {
+		const candidate = preferred + offset;
+		if (await portAvailable(candidate, host)) return candidate;
+	}
+}
+/** Start a detached server process and return its id. */
+function spawnServer(options) {
+	mkdirSync(dirname(options.logPath), { recursive: true });
+	const output = spawn(options.command, [...options.args], {
+		detached: true,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		env: options.env
+	});
+	const stream = createWriteStream(options.logPath);
+	output.stdout?.pipe(stream);
+	output.stderr?.pipe(stream);
+	output.unref();
+	if (output.pid === void 0) throw new Error("the server process did not start");
+	return output.pid;
+}
+/**
+* Wait until the server answers, so a start reports success only once the URL works.
+*
+* @param url - URL to poll.
+* @param timeoutMilliseconds - how long to keep polling.
+* @returns whether the server answered within the budget.
+*/
+async function waitForServer(url, timeoutMilliseconds) {
+	const deadline = Date.now() + timeoutMilliseconds;
+	while (Date.now() < deadline) try {
+		await fetch(url, {
+			method: "GET",
+			redirect: "manual"
+		});
+		return true;
+	} catch {
+		await new Promise((resolveDelay) => {
+			setTimeout(resolveDelay, 250);
+		});
+	}
+	return false;
+}
+/**
+* Wait until the launcher's log carries the authenticated URL.
+*
+* Readiness and the printed line are separate events: the server answers before the
+* launcher finishes its own startup, so the log is polled here rather than read once.
+*
+* @param logPath - the launcher's log file.
+* @param timeoutMilliseconds - how long to keep polling.
+* @returns the printed URL, or undefined when it never appeared.
+*/
+async function waitForAuthenticatedUrl(logPath, timeoutMilliseconds) {
+	const deadline = Date.now() + timeoutMilliseconds;
+	for (;;) {
+		let text = "";
+		try {
+			text = readFileSync(logPath, "utf8");
+		} catch {}
+		const found = /dsh web: (http:\/\/\S+)/u.exec(text);
+		if (found?.[1] !== void 0) return found[1];
+		if (Date.now() >= deadline) return void 0;
+		await new Promise((resolveDelay) => {
+			setTimeout(resolveDelay, 250);
+		});
+	}
+}
+//#endregion
+//#region lib/types/standalone-profile.js
+/**
+* Runtime paths and profile composition for a standalone Plus installation.
+*
+* A standalone consumer installs the distribution from the registry and owns its
+* profile, so this module answers the two questions every command shares: where the
+* DSH home and profile live, and what the profile manifest must contain. The bundle
+* order comes from the installed distribution rather than from a copy here, because
+* the launcher mounts exactly the bundles the profile names and nothing expands a
+* bundle's own list.
+*/
+/** Profile name a standalone installation owns. */
+const STANDALONE_PROFILE = "plus";
+function requireRecord(value, label) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(label + " must be an object");
+	return value;
+}
+function requireStringArray(value, label) {
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(label + " must be a string array");
+	return value;
+}
+/** Resolve the DSH home, honouring the environment override the launcher itself reads. */
+function resolveHome(env = process.env) {
+	const configured = env.DSH_HOME;
+	return configured === void 0 || configured === "" ? join(homedir(), ".dsh") : resolve(configured);
+}
+/**
+* Whether one absolute path is the other or sits beneath it.
+*
+* A path outside the parent has a relative form starting with `..`, which every
+* platform answers the same way. Comparing the text against a literal separator is
+* not: Windows separates with a backslash, so a nested path never matched its own
+* ancestor and every Windows installation reported the distribution as sitting
+* outside its own tree.
+*
+* @param candidate - absolute path to test.
+* @param parent - absolute path that may contain it.
+* @param platform - separating convention, injectable so the Windows answer is
+* testable where the suite runs on a POSIX host.
+* @returns true when the candidate is the parent or inside it.
+*/
+function isWithin(candidate, parent, platform = process.platform) {
+	if (candidate === parent) return true;
+	const path = platform === "win32" ? win32 : posix;
+	const inside = path.relative(parent, candidate);
+	return inside !== "" && !inside.startsWith("..") && !inside.startsWith(path.sep + "..");
+}
+/**
+* Resolve the installed distribution directory from one requiring anchor.
+*
+* The anchor must be a path inside the consumer's own tree. Resolving from this
+* module instead would find the distribution the module itself was loaded from,
+* which is the repository during development and the consumer's install otherwise.
+*
+* @param anchor - `package.json` path or directory in the consumer tree.
+* @returns absolute path to the installed distribution.
+*/
+function resolveDistributionDirectory(anchor) {
+	let resolved;
+	try {
+		resolved = dirname(createRequire(anchor).resolve("@sparkelf/dsh-plus/package.json"));
+	} catch {
+		throw new Error("@sparkelf/dsh-plus is not installed in " + dirname(anchor) + "; run this command from the directory that installed it");
+	}
+	let current = resolve(dirname(anchor));
+	for (;;) {
+		if (isWithin(resolved, current)) return resolved;
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	throw new Error("@sparkelf/dsh-plus resolved outside " + resolve(dirname(anchor)) + " (found " + resolved + "); run this command from the directory that installed it");
+}
+/** The reviewed bundle order and pins the installed distribution declares. */
+function readDistributionProfile(distributionDirectory) {
+	const manifest = requireRecord(JSON.parse(readFileSync(join(distributionDirectory, "package.json"), "utf8")), "Plus distribution manifest");
+	const plus = requireRecord(manifest.dshPlus, "dshPlus");
+	const profile = requireRecord(plus.profile, "dshPlus.profile");
+	const rawDependencies = requireRecord(profile.dependencies, "dshPlus.profile.dependencies");
+	const rawAllowBuilds = requireRecord(profile.allowBuilds, "dshPlus.profile.allowBuilds");
+	const dependencies = {};
+	for (const [name, spec] of Object.entries(rawDependencies)) {
+		if (typeof spec !== "string" || spec === "") throw new Error("dshPlus.profile.dependencies." + name + " must be a non-empty string");
+		dependencies[name] = spec;
+	}
+	const allowBuilds = {};
+	for (const [name, allowed] of Object.entries(rawAllowBuilds)) {
+		if (typeof allowed !== "boolean") throw new Error("dshPlus.profile.allowBuilds." + name + " must be a boolean");
+		allowBuilds[name] = allowed;
+	}
+	const overrides = {};
+	const rawOverrides = profile.overrides === void 0 ? {} : requireRecord(profile.overrides, "dshPlus.profile.overrides");
+	for (const [name, spec] of Object.entries(rawOverrides)) {
+		if (typeof spec !== "string" || spec === "") throw new Error("dshPlus.profile.overrides." + name + " must be a non-empty string");
+		overrides[name] = spec;
+	}
+	const compatibility = requireRecord(plus.compatibility, "dshPlus.compatibility");
+	return {
+		name: String(manifest.name),
+		bundles: requireStringArray(profile.bundles, "dshPlus.profile.bundles"),
+		dependencies,
+		allowBuilds,
+		overrides,
+		dshRange: String(compatibility.dsh),
+		version: String(manifest.version)
+	};
+}
+/**
+* Give the profile its own installed tree, built from the distribution's declarations.
+*
+* The launcher resolves a bundle from the profile directory, so the profile needs its
+* own `node_modules`. Pointing it at the consumer's tree was cheaper, but it made the
+* profile inherit whatever npm had already installed — including the official packages
+* the distribution's `overrides` exist to replace. npm applies `overrides` only from a
+* project's own root, so a profile without its own tree cannot receive them at all, and
+* a patch delivered that way silently never arrives.
+*
+* Installing here makes the profile that root: pnpm reads `overrides` from the
+* profile's own `pnpm-workspace.yaml`, which `writeProfileOverrides` writes before this
+* runs. The install is skipped once the tree exists so a start does not pay for it
+* twice; `dsh-plus apply` remains the command that reinstalls after a change.
+*
+* @param paths - resolved standalone paths.
+* @param consumerDirectory - directory whose `node_modules` holds the installation.
+*/
+function installProfilePackages(paths, consumerDirectory) {
+	if (!existsSync(join(consumerDirectory, "node_modules"))) throw new Error("no node_modules in " + consumerDirectory + "; run npm install there first");
+	const profileModules = join(paths.profileDirectory, "node_modules");
+	if (existsSync(profileModules)) {
+		linkNestedBundles(paths, profileModules);
+		return;
+	}
+	installWithRegistryFallback(paths);
+	alignReplacedPackageNames(profileModules);
+	linkNestedBundles(paths, profileModules);
+}
+/**
+* Install the profile from the first registry that answers.
+*
+* The install fetches a full dependency closure, and a mainland consumer reaches the
+* mirror far faster than the origin. Trying the preferred registry and falling back once
+* keeps a first start quick without failing when the preferred one is unreachable.
+*
+* @param paths - resolved standalone paths.
+*/
+function installWithRegistryFallback(paths) {
+	const registries = registryOrder();
+	for (const [index, registry] of registries.entries()) {
+		const result = spawnSync("pnpm", [
+			"install",
+			"--no-frozen-lockfile",
+			"--registry",
+			registry
+		], {
+			cwd: paths.profileDirectory,
+			stdio: "inherit",
+			shell: process.platform === "win32"
+		});
+		if (result.error !== void 0) throw result.error;
+		if (result.status === 0) return;
+		const next = registries[index + 1];
+		if (next === void 0) throw new Error("pnpm install in the plus profile failed with exit code " + String(result.status));
+		console.log("Install from " + registry + " failed; trying " + next + ".");
+	}
+}
+/**
+* Make each replaced package declare the name of the location it occupies.
+*
+* \`overrides\` installs our build at the official path, but the manifest inside still
+* names our scope. The client module system resolves a loader entry's declared name and
+* then requires the manifest it finds to declare that same name
+* (\`client/modules\`: \`name === expectedPackageName\`); a mismatch makes the package own no
+* browser module at all. The symptom is silent — the packages install, the server starts,
+* and the panels those packages render simply never appear.
+*
+* The rewrite replaces the file rather than writing through it: pnpm hard-links a package
+* manifest into its content-addressed store, so an in-place write would edit every
+* profile sharing that store entry.
+*
+* @param profileModules - the profile's \`node_modules\` directory.
+*/
+function alignReplacedPackageNames(profileModules) {
+	const scoped = join(profileModules, "@deepseek-ai");
+	if (!existsSync(scoped)) return;
+	for (const entry of readdirSync(scoped)) {
+		const manifestPath = join(scoped, entry, "package.json");
+		if (!existsSync(manifestPath)) continue;
+		const declared = JSON.parse(readFileSync(manifestPath, "utf8"));
+		const expected = "@deepseek-ai/" + entry;
+		if (declared.name === expected) continue;
+		const replaced = {
+			...declared,
+			name: expected
+		};
+		const temporary = manifestPath + ".dsh-name";
+		writeFileSync(temporary, JSON.stringify(replaced, null, 2) + "\n");
+		renameSync(temporary, manifestPath);
+	}
+}
+/** The npm registry the distribution installs from by default. */
+const OFFICIAL_REGISTRY = "https://registry.npmjs.org";
+/** The mainland mirror, which serves the same packages and answers faster there. */
+const MAINLAND_REGISTRY = "https://registry.npmmirror.com";
+/**
+* The registries to try, in order, for this machine.
+*
+* A mainland locale reaches the mirror faster than the origin, which is why the Desktop
+* installer already prefers it there. The same choice belongs to the profile install: it
+* fetches a full dependency closure, so the delay is the first thing a consumer notices.
+* `DSH_PLUS_INSTALL_REGISTRY` overrides the choice, and a failure falls back once.
+*
+* @returns registries to try in order.
+*/
+function registryOrder() {
+	const configured = process.env.DSH_PLUS_INSTALL_REGISTRY;
+	if (configured !== void 0 && configured !== "") return [configured, MAINLAND_REGISTRY];
+	const locale = [
+		process.env.LANG,
+		process.env.LC_ALL,
+		Intl.DateTimeFormat().resolvedOptions().locale
+	].filter((value) => value !== void 0).join(" ").toLowerCase();
+	return locale.includes("zh") || locale.includes("cn") ? [MAINLAND_REGISTRY, OFFICIAL_REGISTRY] : [OFFICIAL_REGISTRY, MAINLAND_REGISTRY];
+}
+/**
+* Report whether pnpm can run.
+*
+* The profile installs its own tree so its \`overrides\` apply, and only pnpm reads those
+* from a workspace, so pnpm is a prerequisite the distribution cannot supply. Probing
+* first turns a cryptic failure from the install into a message naming what is missing.
+*
+* @returns \`true\` when pnpm answers with a version.
+*/
+function pnpmAvailable() {
+	return spawnSync("pnpm", ["--version"], {
+		stdio: "pipe",
+		shell: process.platform === "win32",
+		encoding: "utf8"
+	}).status === 0;
+}
+/**
+* The commands that install pnpm, in the order worth trying.
+*
+* Corepack ships with Node and needs no download, so it comes first; npm is the fallback
+* for an installation whose Corepack is absent or disabled. Both are the consumer's own
+* toolchain, which is what lets the first start offer to install rather than only report.
+*
+* @returns commands to try in order, stopping at the first that works.
+*/
+function pnpmInstallCommands() {
+	const registry = registryOrder()[0];
+	if (registry === void 0) return ["corepack enable pnpm", "npm install -g pnpm"];
+	return ["corepack enable pnpm", "npm install -g pnpm --registry " + registry];
+}
+/**
+* The command to show a consumer who declines the automatic install.
+*
+* @returns the preferred command, which is the one the offer runs first.
+*/
+function pnpmInstallCommand() {
+	return pnpmInstallCommands()[0] ?? "npm install -g pnpm";
+}
+/**
+* Expose the distribution's nested packages at the top level the profile searches.
+*
+* The profile resolves a bundle from one directory, so a package npm nested under the
+* distribution is invisible there even though the installation carries it. Linking each
+* one beside the hoisted packages keeps a single installed copy and needs no reinstall.
+*
+* @param paths - resolved standalone paths.
+* @param consumerModules - the consumer's `node_modules` directory.
+*/
+function linkNestedBundles(paths, consumerModules) {
+	const nested = join(paths.distributionDirectory, "node_modules");
+	if (!existsSync(nested)) return;
+	for (const entry of readdirSync(nested)) {
+		if (entry.startsWith("@")) {
+			for (const scoped of readdirSync(join(nested, entry))) linkBundle(consumerModules, join(entry, scoped), join(nested, entry, scoped));
+			continue;
+		}
+		linkBundle(consumerModules, entry, join(nested, entry));
+	}
+}
+/** Link one nested bundle into the consumer's top level when it is not already there. */
+function linkBundle(consumerModules, name, source) {
+	const destination = join(consumerModules, name);
+	if (existsSync(destination)) return;
+	try {
+		symlinkSync(source, destination, "junction");
+	} catch {}
+}
+/** Resolve every path a command needs, without creating anything. */
+function resolvePaths(anchor, env = process.env) {
+	const home = resolveHome(env);
+	return {
+		home,
+		profileDirectory: join(home, "profiles", STANDALONE_PROFILE),
+		distributionDirectory: resolveDistributionDirectory(anchor)
+	};
+}
+/**
+* Write the profile manifest when it is absent, leaving an existing one untouched.
+*
+* The distribution's own plugin dependencies are seeded here so the launcher can
+* resolve every bundle from the profile directory: a bundle the profile cannot
+* resolve fails activation with a module-resolution error, and no step in the
+* launcher expands the distribution's bundle list on its own.
+*
+* The profile also links the consumer's installed packages, because the launcher
+* resolves each bundle from the profile directory rather than from the directory
+* that installed them.
+*
+* @param paths - resolved standalone paths.
+* @param consumerDirectory - directory whose `node_modules` holds the installed packages.
+* @returns whether this call created the manifest.
+*/
+function ensureProfile(paths, consumerDirectory) {
+	const manifestPath = join(paths.profileDirectory, "package.json");
+	const distribution = readDistributionProfile(paths.distributionDirectory);
+	if (existsSync(manifestPath)) {
+		writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds);
+		installProfilePackages(paths, consumerDirectory);
+		return false;
+	}
+	mkdirSync(paths.profileDirectory, { recursive: true });
+	const manifest = {
+		name: "dsh-profile-plus",
+		private: true,
+		type: "module",
+		dependencies: {
+			"@sparkelf/dsh-plus": distribution.version,
+			"@deepseek-ai/dsh": distribution.dshRange,
+			...distribution.dependencies
+		},
+		dsh: { profile: {
+			bundles: distribution.bundles,
+			patchReload: "live"
+		} }
+	};
+	writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+	writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds);
+	installProfilePackages(paths, consumerDirectory);
+	return true;
+}
+/**
+* Record the distribution's package substitutions in the profile workspace.
+*
+* pnpm reads \`overrides\` from \`pnpm-workspace.yaml\` since version 10 and ignores the
+* same key in \`package.json\`, so a profile that carried it in the manifest would
+* silently install the official package the override meant to replace.
+*
+* @param profileDirectory - the standalone profile directory.
+* @param overrides - official package name to published replacement spec.
+*/
+function writeProfileOverrides(profileDirectory, overrides, allowBuilds) {
+	const workspacePath = join(profileDirectory, "pnpm-workspace.yaml");
+	const document = parseDocument(existsSync(workspacePath) ? readFileSync(workspacePath, "utf8") : "");
+	const [documentError] = document.errors;
+	if (documentError !== void 0) throw new Error("Plus profile workspace is not valid YAML", { cause: documentError });
+	if (document.get("packages") === void 0) document.set("packages", ["."]);
+	for (const [name, spec] of Object.entries(overrides)) document.setIn(["overrides", name], spec);
+	for (const [name, allowed] of Object.entries(allowBuilds)) document.setIn(["allowBuilds", name], allowed);
+	if (document.get("nodeLinker") === void 0) document.set("nodeLinker", "hoisted");
+	if (document.get("autoInstallPeers") === void 0) document.set("autoInstallPeers", false);
+	writeFileSync(workspacePath, String(document));
+}
+/** Run git in one directory, returning undefined instead of throwing when asked to. */
+function git(root, args, acceptFailure = false) {
+	const result = spawnSync("git", args, {
+		cwd: root,
+		encoding: "utf8"
+	});
+	if (result.status === 0) return result.stdout.trim();
+	if (acceptFailure) return void 0;
+	const detail = result.stderr.trim();
+	throw new Error("git " + args.join(" ") + " failed" + (detail === "" ? "" : ": " + detail));
+}
+/**
+* Apply the reviewed npm-target patches to the profile's installed packages.
+*
+* A standalone installation runs no `apply` step: it installs the distribution from
+* the registry, links the consumer's packages, and starts. The npm patches a
+* distribution declares therefore need an owner that does not require an official
+* source checkout — the source half of the apply step needs one, this does not.
+*
+* The work is idempotent: a patch whose reverse already applies is left alone, so a
+* second start neither re-applies nor fails. A reinstall restores the published bytes,
+* which is why this runs on every start rather than once.
+*
+* @param distributionDirectory - the installed `@sparkelf/dsh-plus` directory.
+* @param profileDirectory - the standalone profile directory.
+* @returns the labels of the patches that were applied.
+*/
+function applyProfileNpmPatches(distributionDirectory, profileDirectory) {
+	const names = requireRecord(requireRecord(JSON.parse(readFileSync(join(distributionDirectory, "package.json"), "utf8")), "Plus distribution manifest").dshPlus, "dshPlus").patchPackages;
+	if (!Array.isArray(names)) throw new Error("dshPlus.patchPackages must be an array");
+	const applied = [];
+	for (const value of names) {
+		if (typeof value !== "string" || value === "") throw new Error("dshPlus.patchPackages entries must be non-empty strings");
+		const patchPackage = resolveInstalledPackage(distributionDirectory, value);
+		const variants = requireRecord(patchPackage.manifest.dshPatch, value + " dshPatch").variants;
+		if (!Array.isArray(variants)) throw new Error(value + " dshPatch.variants must be an array");
+		for (const entry of variants) {
+			const variant = requireRecord(entry, value + " variant");
+			const target = requireRecord(variant.target, value + " variant target");
+			if (target.kind !== "npm") continue;
+			const targetName = String(target.name);
+			const patched = resolveInstalledPackage(profileDirectory, targetName);
+			const file = resolve(patchPackage.directory, String(variant.file));
+			if (git(patched.directory, [
+				"apply",
+				"--reverse",
+				"--check",
+				file
+			], true) !== void 0) continue;
+			git(patched.directory, ["apply", file]);
+			applied.push(value + " -> " + targetName);
+		}
+	}
+	return applied;
+}
+/** Resolve one installed package's manifest from a requiring directory. */
+function resolveInstalledPackage(from, packageName) {
+	const requireFrom = createRequire(join(from, "package.json"));
+	let manifestPath;
+	try {
+		manifestPath = requireFrom.resolve(packageName + "/package.json");
+	} catch {
+		throw new Error(packageName + " is not installed under " + from);
+	}
+	const manifest = requireRecord(JSON.parse(readFileSync(manifestPath, "utf8")), packageName + " manifest");
+	return {
+		name: packageName,
+		version: String(manifest.version),
+		directory: dirname(manifestPath),
+		manifest
+	};
+}
+//#endregion
+//#region lib/types/standalone-cli.js
+/**
+* The `dsh-plus` command line for a standalone installation.
+*
+* The commands exist because the launcher underneath is a developer surface: it
+* refuses an existing profile, reports a taken port as a module-resolution stack
+* trace, and exits with the terminal. This dispatcher supplies the missing product
+* layer — a profile created on first start, a free port chosen without asking, a
+* server that survives the terminal, and one place to read the URL.
+*/
+/** Milliseconds a start waits for the server to answer before reporting failure. */
+const READY_TIMEOUT_MILLISECONDS = 9e4;
+function parseStartOptions(argv) {
+	let port = DEFAULT_PORT;
+	let host = "127.0.0.1";
+	let open = true;
+	let foreground = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--port" || token === "-p") {
+			const value = argv[index + 1];
+			if (value === void 0 || !/^\d+$/u.test(value)) throw new Error("--port requires a number");
+			port = Number(value);
+			index += 1;
+			continue;
+		}
+		if (token === "--host") {
+			const value = argv[index + 1];
+			if (value === void 0) throw new Error("--host requires a value");
+			host = value;
+			index += 1;
+			continue;
+		}
+		if (token === "--no-open") {
+			open = false;
+			continue;
+		}
+		if (token === "--foreground") {
+			foreground = true;
+			continue;
+		}
+		throw new Error("unknown option: " + token);
+	}
+	return {
+		port,
+		host,
+		open,
+		foreground
+	};
+}
+/**
+* Where the installation that owns this command keeps its packages.
+*
+* A global install places the command in a shared prefix and a local install places
+* it in a project; neither has anything to do with the directory the user happens to
+* be in. The search therefore starts at this module own file and climbs to the tree
+* npm laid out around it.
+*
+* The test is the launcher, not the distribution: inside a workspace the package
+* resolves its own name, so looking for the distribution would stop at the package
+* rather than at the tree that owns every dependency.
+*
+* @returns absolute path to the installation root.
+*/
+function installationRoot() {
+	const here = dirname(fileURLToPath(import.meta.url));
+	let current = here;
+	for (;;) {
+		if (existsSync(join(current, "node_modules", "@deepseek-ai", "dsh"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return here;
+		current = parent;
+	}
+}
+/** The package.json this installation resolves its dependencies from. */
+function installationAnchor() {
+	return join(installationRoot(), "package.json");
+}
+/** The launcher entry this installation must drive. */
+function launcherEntry(anchor) {
+	return createRequire(anchor).resolve("@deepseek-ai/dsh/lib/bin.js");
+}
+/** Run the server in this process, inheriting stdio. */
+function runForeground(entry, port, host, open) {
+	const args = [
+		entry,
+		"--profile",
+		STANDALONE_PROFILE,
+		"--port",
+		String(port),
+		"--host",
+		host
+	];
+	if (!open) args.push("--no-open");
+	return spawnSync(process.execPath, args, { stdio: "inherit" }).status ?? 1;
+}
+async function start(argv) {
+	const options = parseStartOptions(argv);
+	const anchor = installationAnchor();
+	const paths = resolvePaths(anchor);
+	if (!pnpmAvailable()) {
+		const command = pnpmInstallCommand();
+		console.log("pnpm is required to install the plus profile, and was not found.");
+		console.log("Install it with: " + command);
+		if (!await confirm("Install pnpm now?")) {
+			console.log("Install pnpm and run dsh-plus start again.");
+			return 1;
+		}
+		let installed = false;
+		const preferred = registryOrder()[0];
+		for (const candidate of pnpmInstallCommands()) if (spawnSync(candidate, {
+			stdio: "inherit",
+			shell: true,
+			env: preferred === void 0 ? process.env : {
+				...process.env,
+				COREPACK_NPM_REGISTRY: preferred
+			}
+		}).status === 0 && pnpmAvailable()) {
+			installed = true;
+			break;
+		}
+		if (!installed) {
+			console.log("Could not install pnpm automatically.");
+			console.log("Run one of these, then run dsh-plus start again:");
+			for (const candidate of pnpmInstallCommands()) console.log("  " + candidate);
+			return 1;
+		}
+		console.log("pnpm installed.");
+	}
+	const created = ensureProfile(paths, installationRoot());
+	console.log(created ? "Created the plus profile at " + paths.profileDirectory : "Using the existing plus profile");
+	for (const label of applyProfileNpmPatches(paths.distributionDirectory, paths.profileDirectory)) console.log("Applied the reviewed patch " + label);
+	const entry = launcherEntry(anchor);
+	if (options.foreground) return runForeground(entry, options.port, options.host, options.open);
+	const existing = readState(paths.home);
+	if (existing !== void 0) {
+		console.log("Plus is already running at " + existing.url);
+		console.log("Stop it with: dsh-plus stop");
+		return 0;
+	}
+	return startDetached(paths.home, entry, options);
+}
+async function startDetached(home, entry, options) {
+	const port = await choosePort(options.port, options.host);
+	if (port === void 0) {
+		console.error("No free port in the range " + String(options.port) + "-" + String(options.port + 9) + ".");
+		console.error("Pass --port with a free port.");
+		return 1;
+	}
+	if (port !== options.port) console.log("Port " + String(options.port) + " is in use; using " + String(port) + ".");
+	const logPath = join(stateDirectory(home), "server.log");
+	const env = {
+		...process.env,
+		DSH_HOME: home
+	};
+	const args = [
+		entry,
+		"--profile",
+		STANDALONE_PROFILE,
+		"--port",
+		String(port),
+		"--host",
+		options.host,
+		"--no-open"
+	];
+	const pid = spawnServer({
+		command: process.execPath,
+		args,
+		env,
+		logPath
+	});
+	const url = "http://" + options.host + ":" + String(port) + "/";
+	if (!await waitForServer(url, READY_TIMEOUT_MILLISECONDS)) {
+		console.error("The server did not answer within " + String(READY_TIMEOUT_MILLISECONDS / 1e3) + "s.");
+		console.error("Read " + logPath + " for the startup error.");
+		if (isRunning(pid)) process.kill(pid, "SIGTERM");
+		return 1;
+	}
+	const opened = await waitForAuthenticatedUrl(logPath, READY_TIMEOUT_MILLISECONDS) ?? url;
+	writeState(home, {
+		pid,
+		port,
+		url: opened
+	});
+	console.log("Plus is running at " + opened);
+	console.log("Logs: " + logPath);
+	console.log("Stop it with: dsh-plus stop");
+	return 0;
+}
+async function stop() {
+	const { home } = resolvePaths(installationAnchor());
+	const state = readState(home);
+	if (state === void 0) {
+		clearState(home);
+		console.log("Plus is not running.");
+		return 0;
+	}
+	process.kill(state.pid, "SIGTERM");
+	const deadline = Date.now() + STOP_GRACE_MILLISECONDS;
+	while (Date.now() < deadline && isRunning(state.pid)) await new Promise((resolveDelay) => {
+		setTimeout(resolveDelay, 200);
+	});
+	if (isRunning(state.pid)) {
+		console.log("The server did not exit in " + String(STOP_GRACE_MILLISECONDS / 1e3) + "s; forcing it.");
+		process.kill(state.pid, "SIGKILL");
+	}
+	clearState(home);
+	console.log("Plus has stopped.");
+	return 0;
+}
+function status() {
+	const state = readState(resolvePaths(installationAnchor()).home);
+	if (state === void 0) {
+		console.log("Plus is not running.");
+		console.log("Start it with: dsh-plus start");
+		return 0;
+	}
+	console.log("Plus is running at " + state.url);
+	console.log("Process " + String(state.pid) + " on port " + String(state.port));
+	return 0;
+}
+/**
+* Move the installation to a newer published release.
+*
+* The profile pins the distribution exactly, so the new version is written into the
+* profile manifest and reinstalled there. A running server keeps the version it
+* started with, so the command reports that a restart is what makes the change take
+* effect rather than pretending the running process changed underneath the user.
+*/
+async function update(argv) {
+	const checkOnly = argv.includes("--check");
+	const assumeYes = argv.includes("--yes");
+	const paths = resolvePaths(installationAnchor());
+	const distribution = readDistributionProfile(paths.distributionDirectory);
+	const installed = distribution.version;
+	const newer = newerVersion(distribution.name, installed);
+	if (newer === void 0) {
+		console.log("Plus " + installed + " is the newest published release.");
+		return 0;
+	}
+	console.log("Installed: " + installed);
+	console.log("Available: " + newer.version + (newer.publishedAt === void 0 ? "" : " (" + newer.publishedAt + ")"));
+	if (checkOnly) return 0;
+	if (!assumeYes && !await confirm("Install " + newer.version + "?")) {
+		console.log("Nothing changed.");
+		return 0;
+	}
+	const profilePath = join(paths.profileDirectory, "package.json");
+	const profile = JSON.parse(readFileSync(profilePath, "utf8"));
+	const dependencies = profile.dependencies;
+	if (dependencies === null || typeof dependencies !== "object" || Array.isArray(dependencies)) throw new Error("the profile manifest has no dependencies to update");
+	dependencies["@sparkelf/dsh-plus"] = newer.version;
+	writeFileSync(profilePath, JSON.stringify(profile, null, 2) + "\n");
+	console.log("Updated the profile to " + newer.version + "; installing...");
+	if (spawnSync("npm", [
+		"install",
+		"--no-audit",
+		"--no-fund"
+	], {
+		cwd: paths.profileDirectory,
+		stdio: "inherit",
+		env: {
+			...process.env,
+			DSH_HOME: paths.home
+		}
+	}).status !== 0) {
+		console.error("The install failed; the profile still requests " + newer.version + ".");
+		return 1;
+	}
+	console.log("Plus is now " + newer.version + ".");
+	if (readState(paths.home) !== void 0) console.log("The running server still serves " + installed + "; run dsh-plus restart to load the new release.");
+	return 0;
+}
+/** Ask one yes/no question on the terminal. */
+function confirm(question) {
+	return new Promise((resolveAnswer) => {
+		process.stdout.write(question + " [y/N] ");
+		process.stdin.once("data", (chunk) => {
+			const answer = String(chunk).trim().toLowerCase();
+			resolveAnswer(answer === "y" || answer === "yes");
+		});
+	});
+}
+async function doctor() {
+	const paths = resolvePaths(installationAnchor());
+	let failures = 0;
+	const check = (ok, line) => {
+		console.log((ok ? "ok   " : "FAIL ") + line);
+		if (!ok) failures += 1;
+	};
+	check(Number(process.versions.node.split(".")[0]) >= 22, "Node " + process.versions.node + " (needs 22 or newer)");
+	check(existsSync(join(paths.distributionDirectory, "package.json")), "Plus distribution at " + paths.distributionDirectory);
+	check(existsSync(join(paths.profileDirectory, "package.json")), "profile at " + paths.profileDirectory + " (dsh-plus start creates it)");
+	const free = await portAvailable(DEFAULT_PORT);
+	check(true, "port " + String(DEFAULT_PORT) + (free ? " is free" : " is in use; start will choose the next free one"));
+	console.log(failures === 0 ? "No problems found." : String(failures) + " problem(s) found.");
+	return failures === 0 ? 0 : 1;
+}
+const USAGE = [
+	"Usage: dsh-plus <command> [options]",
+	"",
+	"Commands:",
+	"  start     start the server (first run creates the profile)",
+	"  stop      stop the server",
+	"  status    report whether the server is running",
+	"  update    move to a newer distribution release",
+	"  doctor    check this installation",
+	"",
+	"start options:",
+	"  --port <n>     port to prefer (default " + String(DEFAULT_PORT) + "; a taken port moves to the next free one)",
+	"  --host <h>     interface to bind (default 127.0.0.1)",
+	"  --no-open      do not open a browser",
+	"  --foreground   run in this terminal instead of in the background",
+	"",
+	"update options:",
+	"  --check        report the available release without installing it",
+	"  --yes          install without asking"
+].join("\n");
+/**
+* Dispatch one command line.
+*
+* @param argv - arguments after the executable and script name.
+* @returns the process exit code.
+*/
+async function runStandaloneCli(argv) {
+	const [command, ...rest] = argv;
+	if (command === void 0 || command === "--help" || command === "-h" || command === "help") {
+		console.log(USAGE);
+		return 0;
+	}
+	if (command === "start") return await start(rest);
+	if (command === "stop") return stop();
+	if (command === "status") return status();
+	if (command === "update") return await update(rest);
+	if (command === "doctor") return doctor();
+	console.error("unknown command: " + command);
+	console.error(USAGE);
+	return 1;
+}
+//#endregion
 //#region lib/types/bin.js
+/**
+* Dispatch the command line.
+*
+* `apply` remains the materialization command a source-based installation runs; every
+* other word is a standalone lifecycle command. Reaching the dispatcher first keeps
+* one executable for both, so a user who installed the distribution from the registry
+* never needs to know which half owns a command.
+*
+* @returns the process exit code.
+*/
+async function main() {
+	const argv = process.argv.slice(2);
+	if (argv[0] === "apply") {
+		runApply(argv);
+		return 0;
+	}
+	return await runStandaloneCli(argv);
+}
 try {
-	runApply(process.argv.slice(2));
+	process.exitCode = await main();
 } catch (error) {
-	console.error(error instanceof Error ? error.stack : error);
+	console.error(error instanceof Error ? error.message : String(error));
 	process.exitCode = 1;
 }
 //#endregion