@sparkelf/dsh-plus 0.2.0-rc.9 → 0.2.1-alpha.1

package/lib/bin.js

@@ -75,6 +75,565 @@ 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-capabilities.js
+/** Capabilities offered at install time, in interview order. */
+const CAPABILITIES = [
+	{
+		id: "exa",
+		title: "Web search (Exa)",
+		detail: "Search the web through Exa instead of the built-in provider; needs an API key",
+		needsEndpoint: false
+	},
+	{
+		id: "mineru",
+		title: "PDF parsing (MinerU)",
+		detail: "Parse uploaded PDFs locally; the service is installed and started here",
+		needsEndpoint: true
+	},
+	{
+		id: "officecli",
+		title: "Office documents (OfficeCLI)",
+		detail: "Create and open DOCX, XLSX, and PPTX deliverables",
+		needsEndpoint: false
+	},
+	{
+		id: "computer-use",
+		title: "Windows desktop control (computer-use)",
+		detail: "Drive the Windows desktop from WSL through the cua driver",
+		needsEndpoint: false
+	}
+];
+/** Where this command starts MinerU when the capability is enabled. */
+const DEFAULT_MINERU_ENDPOINT = "http://127.0.0.1:8000/file_parse";
+/** File under the deployment home recording which capabilities were enabled. */
+const CAPABILITY_RECORD = "capabilities.json";
+/** Deployment env file the launcher reads as its `user-env` layer. */
+const CAPABILITY_ENV_FILE = ".env";
+/** One prompt on the terminal, resolving the trimmed line the user typed. */
+function ask(question) {
+	return new Promise((resolveAnswer) => {
+		process.stdout.write(question);
+		process.stdin.once("data", (chunk) => {
+			resolveAnswer(String(chunk).trim());
+		});
+	});
+}
+/** Ask one yes/no question, defaulting to yes. */
+async function confirmDefaultYes(question) {
+	const answer = (await ask(question + " [Y/n] ")).toLowerCase();
+	return answer === "" || answer === "y" || answer === "yes";
+}
+/**
+* Interview the user about the optional capabilities.
+*
+* Each is offered on its own line and defaults to enabled, so pressing Enter
+* through the interview produces a deployment whose features work. The answers are
+* returned rather than applied, so a caller can report what it will do before it
+* touches the profile.
+*
+* @param interactive - when false, every capability is enabled without asking.
+* @returns the ids to enable and the values the enabled ones need.
+*/
+async function interviewCapabilities(interactive) {
+	if (!interactive) return { enabled: CAPABILITIES.map((capability) => capability.id) };
+	console.log("");
+	console.log("Optional capabilities. Press Enter to accept the default (all enabled),");
+	console.log("or answer n for any you do not want.");
+	console.log("");
+	const enabled = [];
+	for (const capability of CAPABILITIES) if (await confirmDefaultYes("  Enable " + capability.title + "? (" + capability.detail + ")")) enabled.push(capability.id);
+	let exaApiKey;
+	if (enabled.includes("exa")) {
+		console.log("");
+		console.log("  Exa needs an API key. Create one at https://dashboard.exa.ai/api-keys");
+		const typed = await ask("  Exa API key (leave empty to add it later): ");
+		if (typed !== "") exaApiKey = typed;
+	}
+	let mineruEndpoint;
+	if (enabled.includes("mineru")) {
+		const typed = await ask("  MinerU endpoint [http://127.0.0.1:8000/file_parse]: ");
+		mineruEndpoint = typed === "" ? DEFAULT_MINERU_ENDPOINT : typed;
+	}
+	return {
+		enabled,
+		...exaApiKey === void 0 ? {} : { exaApiKey },
+		...mineruEndpoint === void 0 ? {} : { mineruEndpoint }
+	};
+}
+/**
+* Names this module owns in the deployment env file.
+*
+* Only names the loader accepts here: a `DSH_`-prefixed variable is refused in any `.env` because
+* `DSH_HOME` is itself bootstrap-only and the file could otherwise relocate the home it is read
+* from. MinerU's endpoint therefore travels in the profile layer, which is also where the plugin
+* reads it.
+*/
+const CAPABILITY_ENV_NAMES = ["EXA_API_KEY"];
+/**
+* The deployment env file, with one assignment per enabled capability that reaches
+* its service through the launch environment.
+*
+* Exa reads its key from the launch environment, so a capability the user selected is enabled here
+* as well as in the profile layer. Only the names this interview owns are rewritten: a
+* deployment that keeps its own assignments in the same file keeps them, and
+* deselecting a capability removes the assignment that turned it on.
+*
+* @param answers - the interview's answers.
+* @param existing - the file's current text, when it already exists.
+* @returns the environment file's text.
+*/
+function capabilityEnvironment(answers, existing = "") {
+	const enabled = new Set(answers.enabled);
+	const owned = new Set(CAPABILITY_ENV_NAMES);
+	const carried = /* @__PURE__ */ new Map();
+	for (const line of existing.split("\n")) {
+		const parsed = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
+		if (parsed?.[1] !== void 0 && owned.has(parsed[1])) carried.set(parsed[1], parsed[2] ?? "");
+	}
+	const kept = existing.split("\n").filter((line) => {
+		const name = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+		return line.trim() !== "" && !line.trimStart().startsWith("#") && (name === void 0 || !owned.has(name));
+	});
+	const written = ["# Written by dsh-plus start from the capability interview. Enabling or", "# disabling a capability rewrites the lines below; other lines are kept."];
+	if (enabled.has("exa")) {
+		const key = answers.exaApiKey ?? carried.get("EXA_API_KEY");
+		if (key !== void 0 && key !== "") written.push("EXA_API_KEY=" + key);
+	}
+	return [...written, ...kept].join("\n") + "\n";
+}
+/**
+* The profile patch layer that turns the selected capabilities on.
+*
+* The file is data the profile's loader merges, so enabling a capability writes a
+* row rather than editing the deployment. An empty selection still writes the file,
+* because a layer that exists and mounts nothing is how a previously enabled
+* capability is turned back off.
+*
+* The profile's own layer is a separate file with its own name: a deployment that
+* configured something by hand keeps it, and the capability rows are rewritten
+* whole on every start.
+*
+* @param answers - the interview's answers.
+* @returns the patch layer's YAML text.
+*/
+/**
+* The patch rows a previous version of this file carried, minus the ones this module owns.
+*
+* The module writes a fixed set of rows, so everything else in the file belongs to the
+* deployment. A row starts at a top-level `- ` entry and runs to the next one, which keeps
+* each row's own config and comments with it.
+*
+* @param existing - the file's current text.
+* @returns the rows to write back after this module's own.
+*/
+function foreignPatchRows(existing) {
+	if (existing.trim() === "") return [];
+	const lines = existing.split("\n");
+	const rows = [];
+	let current = null;
+	for (const line of lines) {
+		if (/^-\s/.test(line)) {
+			if (current !== null) rows.push(current);
+			current = [line];
+			continue;
+		}
+		if (current !== null) current.push(line);
+	}
+	if (current !== null) rows.push(current);
+	const ownedHeads = new Set(["insert", "web"]);
+	return rows.filter((row) => {
+		const head = row[0] ?? "";
+		const id = /^-\s+id:\s*(\S+)/.exec(head)?.[1];
+		if (id !== void 0) return !ownedHeads.has(id);
+		if (/^-\s+insert:\s*$/.test(head)) {
+			const ownedChildren = new Set([
+				"web-search-exa",
+				"computer-use",
+				"computer-use-cua-driver-mcp",
+				"mineru"
+			]);
+			return row.filter((line, index) => {
+				if (index === 0) return false;
+				const childId = /^\s+-\s+id:\s*(\S+)/.exec(line)?.[1];
+				return childId === void 0 || !ownedChildren.has(childId);
+			}).some((line) => /^\s+-\s+/.test(line));
+		}
+		return true;
+	}).map((row) => row.join("\n").trimEnd());
+}
+function capabilityPatchLayer(answers, existing = "") {
+	const enabled = new Set(answers.enabled);
+	const rows = [];
+	if (enabled.has("exa")) rows.push("    - id: web-search-exa", "      name: '@deepseek-ai/dsh-web-search-exa'", "      config:", "        searchType: auto", "        numResults: 8");
+	if (enabled.has("computer-use")) rows.push("    - id: computer-use", "      name: '@deepseek-ai/dsh-computer-use'", "    - id: computer-use-cua-driver-mcp", "      name: '@deepseek-ai/dsh-experimental-computer-use-cua-driver-mcp'");
+	if (enabled.has("officecli")) rows.push("    - id: officecli", "      name: '@sparkelf/dsh-officecli'");
+	if (enabled.has("mineru")) rows.push("    - id: mineru", "      name: '@sparkelf/dsh-mineru'", "      config:", "        endpoint: " + (answers.mineruEndpoint ?? "http://127.0.0.1:8000/file_parse"));
+	const lines = ["# Written by dsh-plus start from the capability interview. Enabling or disabling a capability", "# rewrites this file; edits here are replaced."];
+	const foreign = foreignPatchRows(existing);
+	if (rows.length > 0) lines.push("- insert:", ...rows);
+	else lines.push("[]");
+	if (enabled.has("exa")) lines.push("", "# Route web_search through Exa rather than the built-in provider.", "- id: web", "  config:", "    searchProvider: exa");
+	if (foreign.length > 0) lines.push("", "# Rows this file carried before the capability interview; kept verbatim.", ...foreign);
+	return lines.join("\n") + "\n";
+}
+/** Run one command, reporting a failure rather than throwing. */
+function runStep(command, args) {
+	return spawnSync(command, [...args], { stdio: "inherit" }).status === 0;
+}
+/**
+* The capability record a previous configured run wrote, or `undefined` when none exists.
+*
+* The record is what lets a later run report the deployment's answers instead of asking
+* again. A malformed or unreadable file is treated as absent rather than fatal: it is a
+* convenience cache, and refusing to boot over it would strand a deployment whose record
+* was corrupted by an interrupted write.
+*
+* @param home - the deployment home holding the record.
+* @returns the enabled ids, and the MinerU endpoint when the record carries one.
+*/
+function readCapabilityRecord(home) {
+	const path = join(home, CAPABILITY_RECORD);
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const record = parsed;
+	if (!Array.isArray(record.enabled)) return void 0;
+	return {
+		enabled: record.enabled.filter((id) => typeof id === "string"),
+		...typeof record.mineruEndpoint === "string" ? { mineruEndpoint: record.mineruEndpoint } : {}
+	};
+}
+/**
+* The capabilities a deployment actually has mounted, read from the files the loader and
+* the launch environment consume.
+*
+* A record is a cache of an earlier answer and can drift from the deployment — a profile
+* layer edited by hand, a record deleted, a plugin removed from the distribution. What a
+* capability is *doing* is decided by the profile patch rows and the env file, so that is
+* what a report reads.
+*
+* @param profilePatchText - the profile layer's YAML text.
+* @param envText - the deployment env file's text.
+* @returns the ids found in the profile layer and the env names present.
+*/
+function detectEnabledCapabilities(profilePatchText, envText) {
+	const mounted = [];
+	if (/^\s*- id: web-search-exa\s*$/mu.test(profilePatchText)) mounted.push("exa");
+	if (/^\s*- id: mineru\s*$/mu.test(profilePatchText)) mounted.push("mineru");
+	if (/^\s*- id: officecli\s*$/mu.test(profilePatchText)) mounted.push("officecli");
+	if (/^\s*- id: computer-use\s*$/mu.test(profilePatchText)) mounted.push("computer-use");
+	const env = [];
+	for (const line of envText.split("\n")) {
+		const name = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+		if (name !== void 0 && !env.includes(name)) env.push(name);
+	}
+	return {
+		mounted,
+		env
+	};
+}
+/**
+* The patch row one capability mounts, as a list of YAML lines, or `undefined` when the
+* capability is turned on by something other than a row this module owns.
+*
+* MinerU is enabled by a row too, but its endpoint is per-deployment, so the caller passes
+* the answers rather than a fixed row.
+*
+* @param id - the capability id.
+* @returns the insert payload lines, without the surrounding `- insert:` entry.
+*/
+function capabilityRows(id) {
+	if (id === "exa") return [
+		"    - id: web-search-exa",
+		"      name: '@deepseek-ai/dsh-web-search-exa'",
+		"      config:",
+		"        searchType: auto",
+		"        numResults: 8"
+	];
+	if (id === "officecli") return ["    - id: officecli", "      name: '@sparkelf/dsh-officecli'"];
+	if (id === "computer-use") return [
+		"    - id: computer-use",
+		"      name: '@deepseek-ai/dsh-computer-use'",
+		"    - id: computer-use-cua-driver-mcp",
+		"      name: '@deepseek-ai/dsh-experimental-computer-use-cua-driver-mcp'"
+	];
+}
+/** The row ids a capability owns in the profile layer. */
+function capabilityRowIds(id) {
+	if (id === "exa") return ["web-search-exa"];
+	if (id === "officecli") return ["officecli"];
+	if (id === "mineru") return ["mineru"];
+	if (id === "computer-use") return ["computer-use", "computer-use-cua-driver-mcp"];
+	return [];
+}
+/**
+* One capability's effect, added to or removed from an existing profile layer without
+* disturbing the rest of the file.
+*
+* `dsh-plus start` owns the whole layer and rewrites it from the interview's answers, which
+* is correct for an install that answered once and never edits afterwards. A deployment
+* that maintains its own rows in that same layer cannot be served that way: replacing the
+* file drops every row the operator wrote. This edits the rows this module owns and leaves
+* every other entry, comment, and blank line exactly where it was.
+*
+* @param existing - the layer's current YAML text.
+* @param id - the capability to add or remove.
+* @param enable - whether to add the capability.
+* @param mineruEndpoint - the endpoint to write when enabling MinerU.
+* @returns the layer's new text.
+*/
+function editCapabilityPatchLayer(existing, id, enable, mineruEndpoint) {
+	const withoutRows = dropOwnedRows(existing, capabilityRowIds(id), id === "exa");
+	const mineruRows = [
+		"    - id: mineru",
+		"      name: '@sparkelf/dsh-mineru'",
+		"      config:",
+		"        endpoint: " + (mineruEndpoint ?? "http://127.0.0.1:8000/file_parse")
+	];
+	const rows = id === "mineru" && enable ? mineruRows : capabilityRows(id);
+	const trimmed = (enable && rows !== void 0 ? insertCapabilityRows(withoutRows, rows, id === "exa") : withoutRows.text).replace(/\n+$/u, "");
+	return trimmed === "" ? "\n" : trimmed + "\n";
+}
+/**
+* Remove the rows one capability owns, and for Exa the `web` selector row that routes
+* search to it.
+*
+* A row is dropped with the block that belongs to it: the `- id:` line plus its indented
+* continuation lines, and any comment line directly above that documented it. Comment and
+* blank lines separating it from the next entry stay, so the surrounding file keeps its
+* shape.
+*
+* @param existing - the layer's current YAML text.
+* @param ids - the row ids this capability owns.
+* @param withSelector - whether the capability also owns the shared `web` selector row.
+* @returns the remaining text and whether anything was actually removed.
+*/
+function dropOwnedRows(existing, ids, withSelector) {
+	const lines = existing.split("\n");
+	const out = [];
+	let removed = false;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		const match = /^(\s*)- id:\s*(\S+)\s*$/.exec(line);
+		const isSelector = withSelector && match?.[2] === "web" && match[1] === "";
+		if (match === null || !ids.includes(match[2] ?? "") && !isSelector) {
+			out.push(line);
+			continue;
+		}
+		removed = true;
+		const indent = match[1] ?? "";
+		while (out.length > 0) {
+			const previous = out[out.length - 1] ?? "";
+			if (previous.trimStart().startsWith("#") && previous.trim() !== "") out.pop();
+			else break;
+		}
+		for (index += 1; index < lines.length; index += 1) {
+			const next = lines[index] ?? "";
+			if (next.trim() === "") {
+				const after = lines[index + 1] ?? "";
+				if (after !== "" && (after.startsWith(indent + " ") || after.startsWith(indent + "	") || after.trimStart().startsWith("#"))) continue;
+				index -= 1;
+				break;
+			}
+			if ((/^\s*/.exec(next)?.[0] ?? "").length > indent.length) continue;
+			index -= 1;
+			break;
+		}
+	}
+	return {
+		text: out.join("\n"),
+		removed
+	};
+}
+/**
+* Add a capability's rows to the layer, creating the `- insert:` entry when the file has
+* none and appending to the existing one otherwise.
+*
+* The loader indexes inserted rows under the layer that inserted them, so appending to an
+* existing `- insert:` list and adding a second one both work; appending keeps the file
+* readable instead of growing one `- insert:` per capability.
+*
+* @param state - the layer with this capability's own rows already removed.
+* @param rows - the insert payload lines to add.
+* @param withSelector - whether Exa's `web` selector row must also be present.
+* @returns the layer's new text.
+*/
+function insertCapabilityRows(state, rows, withSelector) {
+	const lines = state.text.split("\n");
+	const insertIndex = lines.findIndex((line) => /^- insert:\s*$/.test(line));
+	if (insertIndex >= 0) {
+		let end = insertIndex + 1;
+		while (end < lines.length) {
+			const line = lines[end] ?? "";
+			if (line.trim() === "" || /^\s/.test(line)) end += 1;
+			else break;
+		}
+		while (end > insertIndex + 1 && (lines[end - 1] ?? "").trim() === "") end -= 1;
+		lines.splice(end, 0, ...rows);
+	} else {
+		const emptyIndex = lines.findIndex((line) => line.trim() === "[]");
+		if (emptyIndex >= 0) lines.splice(emptyIndex, 1, "- insert:", ...rows);
+		else {
+			const trailing = lines.length > 0 && (lines[lines.length - 1] ?? "") === "" ? lines.pop() ?? "" : void 0;
+			lines.push("- insert:", ...rows);
+			if (trailing !== void 0) lines.push(trailing);
+		}
+	}
+	if (withSelector && !/^\s*- id: web\s*$/mu.test(lines.join("\n"))) lines.push("", "# Route web_search through Exa rather than the built-in provider.", "- id: web", "  config:", "    searchProvider: exa", "    fetchProvider: http");
+	return lines.join("\n");
+}
+/**
+* Install and start the backing services the selected capabilities need.
+*
+* Enabling a capability means the deployment expects its service to answer, so the
+* command that offers the choice is also the command that provides it. Each step
+* reports what it is doing and, on failure, the command a user can run by hand —
+* a missing runtime is a fact about the host, not a reason to abandon the install.
+*
+* @param answers - the interview's answers.
+* @param home - the deployment home, where generated service units are recorded.
+* @returns the ids whose service is ready.
+*/
+async function installCapabilityServices(answers, home) {
+	const enabled = new Set(answers.enabled);
+	const ready = [];
+	mkdirSync(home, { recursive: true });
+	writeFileSync(join(home, CAPABILITY_RECORD), JSON.stringify({
+		enabled: [...answers.enabled],
+		...answers.mineruEndpoint === void 0 ? {} : { mineruEndpoint: answers.mineruEndpoint }
+	}, null, 2) + "\n");
+	if (enabled.has("mineru")) {
+		console.log("");
+		console.log("  MinerU: installing the parser and starting its service...");
+		if (installMineru(home) && startMineru(home)) {
+			ready.push("mineru");
+			console.log("  MinerU: ready at " + (answers.mineruEndpoint ?? "http://127.0.0.1:8000/file_parse"));
+		} else {
+			console.log("  MinerU: not installed. Install it later with:");
+			console.log("    pip install -U \"mineru[core]\"");
+			console.log("    mineru-api --host 127.0.0.1 --port 8000");
+		}
+	}
+	if (enabled.has("officecli")) ready.push("officecli");
+	if (enabled.has("computer-use")) if (desktopDriverAvailable()) ready.push("computer-use");
+	else {
+		console.log("");
+		console.log("  computer-use: the cua driver was not found on PATH. The plugin is");
+		console.log("  still mounted, so it starts once the driver is installed:");
+		console.log("    install the cua-driver release for this architecture, then restart");
+	}
+	return ready;
+}
+/**
+* Install MinerU when it is absent and start its API service.
+*
+* MinerU is a Python package whose API server answers on a local port; the profile
+* points at that port. The parser is installed into a virtual environment under the
+* deployment home and an existing one is upgraded rather than skipped, so enabling
+* the capability keeps the parser current without touching the system interpreter.
+*
+* @param home - the deployment home that owns the venv.
+* @returns whether the package is installed; not whether it answered.
+*/
+function installMineru(home) {
+	const python = pythonInterpreter();
+	if (python === void 0) {
+		console.log("  MinerU: no Python interpreter found on PATH.");
+		return false;
+	}
+	const venv = join(home, ".mineru-venv");
+	if (!runStep(python, [
+		"-m",
+		"venv",
+		venv
+	])) return false;
+	return runStep(join(venv, "bin", "python"), [
+		"-m",
+		"pip",
+		"install",
+		"-U",
+		"mineru[all]"
+	]);
+}
+/**
+* Start the MinerU API server as a background service when none answers yet.
+*
+* The service has to outlive the install command, so it is registered with the
+* host's service manager when one is available and otherwise started detached.
+*
+* @returns whether the server is running after this call.
+*/
+function startMineru(home) {
+	const api = mineruApiBinary(home);
+	if (api === void 0) return false;
+	if (mineruAnswers()) return true;
+	if (spawnSync("systemctl", ["--version"], { stdio: "ignore" }).status === 0) {
+		writeFileSync("/etc/systemd/system/mineru-api.service", [
+			"[Unit]",
+			"Description=MinerU document parsing API for DeepSeek Harness Plus",
+			"After=network-online.target",
+			"Wants=network-online.target",
+			"",
+			"[Service]",
+			"Type=simple",
+			"User=root",
+			"ExecStart=" + api + " --host 127.0.0.1 --port 8000",
+			"Restart=on-failure",
+			"RestartSec=2",
+			"TimeoutStopSec=15",
+			"",
+			"[Install]",
+			"WantedBy=multi-user.target",
+			""
+		].join("\n"));
+		spawnSync("systemctl", ["daemon-reload"], { stdio: "ignore" });
+		return spawnSync("systemctl", [
+			"enable",
+			"--now",
+			"mineru-api.service"
+		], { stdio: "ignore" }).status === 0;
+	}
+	console.log("  MinerU: start the API server with:");
+	console.log("    " + api + " --host 127.0.0.1 --port 8000");
+	return false;
+}
+/** The Python interpreter to install MinerU with, preferring python3. */
+function pythonInterpreter() {
+	return ["python3", "python"].find((candidate) => spawnSync(candidate, ["--version"], { stdio: "ignore" }).status === 0);
+}
+/**
+* The MinerU API entry point, wherever the install placed it.
+*
+* The venv this command creates comes first: it is the interpreter the parser was
+* installed into, so its `mineru-api` is the one that can import MinerU. A binary on
+* PATH is a fallback for a deployment that installed MinerU some other way.
+*
+* @param home - the deployment home that owns the venv.
+* @returns the command to run, or `undefined` when none answers.
+*/
+function mineruApiBinary(home) {
+	return [join(home, ".mineru-venv", "bin", "mineru-api"), "mineru-api"].find((candidate) => spawnSync(candidate, ["--help"], { stdio: "ignore" }).status === 0);
+}
+/** Whether a MinerU API server already answers on the default port. */
+function mineruAnswers() {
+	return spawnSync("curl", [
+		"-sf",
+		"-o",
+		"/dev/null",
+		"--max-time",
+		"3",
+		"http://127.0.0.1:8000/docs"
+	], { stdio: "ignore" }).status === 0;
+}
+/** Whether the Windows-side desktop driver answers from this shell. */
+function desktopDriverAvailable() {
+	return spawnSync("cua-driver", ["--version"], { stdio: "ignore" }).status === 0;
+}
+//#endregion
 //#region lib/types/standalone-server.js
 /**
 * Process lifecycle for one standalone Plus server.
@@ -242,8 +801,55 @@ async function waitForAuthenticatedUrl(logPath, timeoutMilliseconds) {
 * the launcher mounts exactly the bundles the profile names and nothing expands a
 * bundle's own list.
 */
-/** Profile name a standalone installation owns. */
+/** Profile name a standalone installation owns when its package declares none. */
 const STANDALONE_PROFILE = "plus";
+/**
+* Read the deployment facts the installing package declares.
+*
+* A standalone package describes the profile it materializes and the capabilities it
+* omits, so a reduced variant owns a differently named profile and a reduced install
+* without the distribution naming either. The declaration travels with the package
+* because npm resolves the tree long before any command of ours runs.
+*
+* @param anchor - path inside the installing package's tree.
+* @param fallback - profile name to use when the declaration is absent.
+* @returns the declared profile name and omitted capabilities.
+*/
+function readStandaloneDeclaration(anchor, fallback = STANDALONE_PROFILE) {
+	let current = resolve(anchor);
+	for (;;) {
+		const declared = readStandaloneFacts(join(current, "package.json"));
+		if (declared !== void 0) return declared;
+		const parent = dirname(current);
+		if (parent === current) return {
+			profileName: fallback,
+			omittedPackages: {}
+		};
+		current = parent;
+	}
+}
+/** Read one manifest's standalone declaration, or undefined when it carries none. */
+function readStandaloneFacts(manifestPath) {
+	if (!existsSync(manifestPath)) return void 0;
+	let standalone;
+	try {
+		standalone = JSON.parse(readFileSync(manifestPath, "utf8")).dshPlusStandalone;
+	} catch {
+		return;
+	}
+	const profile = standalone?.profile;
+	if (standalone === void 0 || typeof profile !== "string" || profile === "") return void 0;
+	const rawOmitted = standalone.omittedPackages;
+	const omittedPackages = {};
+	if (rawOmitted !== void 0 && typeof rawOmitted === "object" && !Array.isArray(rawOmitted)) for (const [name, spec] of Object.entries(rawOmitted)) {
+		if (typeof spec !== "string" || spec === "") throw new Error("dshPlusStandalone.omittedPackages." + name + " must be a non-empty string");
+		omittedPackages[name] = spec;
+	}
+	return {
+		profileName: profile,
+		omittedPackages
+	};
+}
 function requireRecord(value, label) {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(label + " must be an object");
 	return value;
@@ -524,9 +1130,12 @@ function linkBundle(consumerModules, name, source) {
 /** Resolve every path a command needs, without creating anything. */
 function resolvePaths(anchor, env = process.env) {
 	const home = resolveHome(env);
+	const declaration = readStandaloneDeclaration(anchor);
 	return {
 		home,
-		profileDirectory: join(home, "profiles", STANDALONE_PROFILE),
+		profileName: declaration.profileName,
+		omittedPackages: declaration.omittedPackages,
+		profileDirectory: join(home, "profiles", declaration.profileName),
 		distributionDirectory: resolveDistributionDirectory(anchor)
 	};
 }
@@ -550,7 +1159,7 @@ 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);
+		writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds, paths.omittedPackages);
 		installProfilePackages(paths, consumerDirectory);
 		return false;
 	}
@@ -570,7 +1179,7 @@ function ensureProfile(paths, consumerDirectory) {
 		} }
 	};
 	writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
-	writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds);
+	writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds, paths.omittedPackages);
 	installProfilePackages(paths, consumerDirectory);
 	return true;
 }
@@ -584,13 +1193,14 @@ function ensureProfile(paths, consumerDirectory) {
 * @param profileDirectory - the standalone profile directory.
 * @param overrides - official package name to published replacement spec.
 */
-function writeProfileOverrides(profileDirectory, overrides, allowBuilds) {
+function writeProfileOverrides(profileDirectory, overrides, allowBuilds, omittedPackages) {
 	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, spec] of Object.entries(omittedPackages)) 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);
@@ -681,11 +1291,14 @@ function resolveInstalledPackage(from, packageName) {
 */
 /** Milliseconds a start waits for the server to answer before reporting failure. */
 const READY_TIMEOUT_MILLISECONDS = 9e4;
+/** Profile patch file the capability interview rewrites (the profile's user layer). */
+const CAPABILITY_PATCH_FILE = "cordis.patch.yml";
 function parseStartOptions(argv) {
 	let port = DEFAULT_PORT;
 	let host = "127.0.0.1";
 	let open = true;
 	let foreground = false;
+	let capabilities;
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
 		if (token === "--port" || token === "-p") {
@@ -710,13 +1323,41 @@ function parseStartOptions(argv) {
 			foreground = true;
 			continue;
 		}
+		if (token === "--capabilities") {
+			const value = argv[index + 1];
+			if (value === void 0) throw new Error("--capabilities requires a comma-separated list, or an empty string for none");
+			const stated = value === "" ? [] : value.split(",").map((entry) => entry.trim()).filter((entry) => entry !== "");
+			const offered = new Set(CAPABILITIES.map((capability) => capability.id));
+			for (const id of stated) if (!offered.has(id)) throw new Error("unknown capability \"" + id + "\"; this release offers " + [...offered].join(", "));
+			capabilities = stated;
+			index += 1;
+			continue;
+		}
 		throw new Error("unknown option: " + String(token));
 	}
 	return {
 		port,
 		host,
 		open,
-		foreground
+		foreground,
+		capabilities
+	};
+}
+/**
+* Resolve a stated capability selection.
+*
+* An unattended install states what it wants instead of answering the interview, so a
+* name it does not offer has to fail here rather than silently enable nothing: the
+* deployment would otherwise start with a capability the caller believes it selected.
+*
+* @param ids - capability ids the caller selected.
+* @returns the answers the interview would have returned.
+*/
+function selectCapabilities(ids) {
+	const selected = [...new Set(ids)];
+	return {
+		enabled: selected,
+		...selected.includes("mineru") ? { mineruEndpoint: DEFAULT_MINERU_ENDPOINT } : {}
 	};
 }
 /**
@@ -747,16 +1388,35 @@ function installationRoot() {
 function installationAnchor() {
 	return join(installationRoot(), "package.json");
 }
+/**
+* Path to the installed command's own file, which is where a declaration lookup starts.
+*
+* The declaration belongs to the package the user installed, and that package is a
+* sibling of this module rather than an ancestor: a variant's forwarder imports this
+* CLI in-process, so `import.meta.url` names `@sparkelf/dsh-plus` while the installed
+* command is the variant. `process.argv[1]` is the entry that was actually invoked,
+* which is the package whose declaration applies.
+*
+* Walking out from the installation root cannot reach it either: that root is the
+* project the user ran the command in, so every variant would fall back to the full
+* profile and keep the capabilities it excluded.
+*
+* @returns absolute path to the invoked command, or this module when argv carries none.
+*/
+function declarationAnchor() {
+	const invoked = process.argv[1];
+	return invoked === void 0 || invoked === "" ? fileURLToPath(import.meta.url) : resolve(invoked);
+}
 /** 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) {
+function runForeground(entry, profileName, port, host, open) {
 	const args = [
 		entry,
 		"--profile",
-		STANDALONE_PROFILE,
+		profileName,
 		"--port",
 		String(port),
 		"--host",
@@ -768,7 +1428,7 @@ function runForeground(entry, port, host, open) {
 async function start(argv) {
 	const options = parseStartOptions(argv);
 	const anchor = installationAnchor();
-	const paths = resolvePaths(anchor);
+	const paths = resolvePaths(declarationAnchor());
 	if (!pnpmAvailable()) {
 		const command = pnpmInstallCommand();
 		console.log("pnpm is required to install the plus profile, and was not found.");
@@ -799,19 +1459,29 @@ async function start(argv) {
 		console.log("pnpm installed.");
 	}
 	const created = ensureProfile(paths, installationRoot());
-	console.log(created ? "Created the plus profile at " + paths.profileDirectory : "Using the existing plus profile");
+	console.log(created ? "Created the " + paths.profileName + " profile at " + paths.profileDirectory : "Using the existing " + paths.profileName + " profile");
 	for (const label of applyProfileNpmPatches(paths.distributionDirectory, paths.profileDirectory)) console.log("Applied the reviewed patch " + label);
+	const answers = created || !existsSync(join(paths.home, "capabilities.json")) ? options.capabilities === void 0 ? await interviewCapabilities(true) : selectCapabilities(options.capabilities) : void 0;
+	if (answers !== void 0) {
+		const ready = await installCapabilityServices(answers, paths.home);
+		writeCapabilityPatch(paths.profileDirectory, answers);
+		writeCapabilityEnvironment(paths.home, answers);
+		console.log("  Enabled: " + (answers.enabled.length === 0 ? "(none)" : answers.enabled.join(", ")));
+		if (answers.enabled.length > 0) console.log("  Services ready: " + (ready.length === 0 ? "(none)" : ready.join(", ")));
+		if (answers.enabled.includes("exa") && answers.exaApiKey === void 0) console.log("  Exa: add EXA_API_KEY to " + join(paths.home, CAPABILITY_ENV_FILE) + " when you have a key.");
+	}
 	const entry = launcherEntry(anchor);
-	if (options.foreground) return runForeground(entry, options.port, options.host, options.open);
+	if (options.foreground) return runForeground(entry, paths.profileName, 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);
+	return startDetached(paths, entry, options);
 }
-async function startDetached(home, entry, options) {
+async function startDetached(paths, entry, options) {
+	const home = paths.home;
 	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) + ".");
@@ -819,15 +1489,15 @@ async function startDetached(home, entry, options) {
 		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 logPath = join(stateDirectory(paths.home), "server.log");
 	const env = {
 		...process.env,
-		DSH_HOME: home
+		DSH_HOME: paths.home
 	};
 	const args = [
 		entry,
 		"--profile",
-		STANDALONE_PROFILE,
+		paths.profileName,
 		"--port",
 		String(port),
 		"--host",
@@ -942,6 +1612,40 @@ async function update(argv) {
 	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;
 }
+/**
+* Write the profile's capability patch layer.
+*
+* The profile's loader merges this file, so enabling a capability is a data change
+* rather than an edit to the deployment. Writing it on every configured run also
+* turns a capability back off when the interview no longer selects it.
+*
+* @param profileDirectory - the profile whose layer is replaced.
+* @param answers - the interview's answers.
+*/
+function writeCapabilityPatch(profileDirectory, answers) {
+	const path = join(profileDirectory, CAPABILITY_PATCH_FILE);
+	const existing = existsSync(path) ? readFileSync(path, "utf8") : void 0;
+	if (existing !== void 0 && !existing.includes("Written by dsh-plus start from the capability interview.")) {
+		writeFileSync(path + ".before-capabilities", existing);
+		console.log("  Kept the existing profile layer at cordis.patch.yml.before-capabilities");
+	}
+	writeFileSync(path, capabilityPatchLayer(answers, existing ?? ""));
+}
+/**
+* Write the deployment's capability environment file.
+*
+* MinerU is switched on by the presence of its endpoint and Exa reads its key from
+* the launch environment, so the answers reach those two through `$DSH_HOME/.env`
+* rather than through the profile layer. The file is replaced whole on every
+* configured start, which is also how a capability the user dropped stops applying.
+*
+* @param home - the deployment home whose env file the launcher reads.
+* @param answers - the interview's answers.
+*/
+function writeCapabilityEnvironment(home, answers) {
+	const path = join(home, CAPABILITY_ENV_FILE);
+	writeFileSync(path, capabilityEnvironment(answers, existsSync(path) ? readFileSync(path, "utf8") : ""));
+}
 /** Ask one yes/no question on the terminal. */
 function confirm(question) {
 	return new Promise((resolveAnswer) => {
@@ -952,6 +1656,134 @@ function confirm(question) {
 		});
 	});
 }
+/**
+* Report and change which optional capabilities this deployment has enabled.
+*
+* The interview runs once, at install time, and a deployment that answered it keeps its
+* answers — so this is the only way to see what it chose or to change one answer later.
+* The report is read from the profile layer and the env file rather than from the record,
+* because those two are what the loader and the launch environment actually consume: a
+* record deleted, or a layer edited by hand, would otherwise describe a deployment that
+* does not exist.
+*
+* `--enable` and `--disable` edit only the rows this module owns. The profile layer is
+* shared with rows an operator wrote themselves, so it is never replaced wholesale.
+*
+* @param argv - arguments after the command word.
+* @returns the process exit code.
+*/
+function capabilities(argv) {
+	const paths = resolvePaths(installationAnchor());
+	const patchPath = join(paths.profileDirectory, CAPABILITY_PATCH_FILE);
+	const envPath = join(paths.home, CAPABILITY_ENV_FILE);
+	const patchText = existsSync(patchPath) ? readFileSync(patchPath, "utf8") : "";
+	const envText = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+	const actual = detectEnabledCapabilities(patchText, envText);
+	const record = readCapabilityRecord(paths.home);
+	let enable = [];
+	let disable = [];
+	let asJson = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--json") {
+			asJson = true;
+			continue;
+		}
+		if (token === "--enable" || token === "--disable") {
+			const value = argv[index + 1];
+			const ids = (value ?? "").split(",").map((id) => id.trim()).filter((id) => id !== "");
+			if (value === void 0 || ids.length === 0) {
+				console.error(token + " requires a comma-separated list of capability ids");
+				return 1;
+			}
+			const unknown = ids.filter((id) => !CAPABILITIES.some((capability) => capability.id === id));
+			if (unknown.length > 0) {
+				console.error("unknown capability: " + unknown.join(", "));
+				console.error("Known: " + CAPABILITIES.map((capability) => capability.id).join(", "));
+				return 1;
+			}
+			if (token === "--enable") enable = [...new Set([...enable, ...ids])];
+			else disable = [...new Set([...disable, ...ids])];
+			index += 1;
+			continue;
+		}
+		console.error("unknown option: " + String(token));
+		return 1;
+	}
+	const conflicting = enable.filter((id) => disable.includes(id));
+	if (conflicting.length > 0) {
+		console.error("cannot both enable and disable: " + conflicting.join(", "));
+		return 1;
+	}
+	if (enable.length > 0 || disable.length > 0) {
+		const enabledNow = new Set(actual.mounted);
+		let nextPatch = patchText;
+		for (const id of enable) {
+			nextPatch = editCapabilityPatchLayer(nextPatch, id, true, record?.mineruEndpoint);
+			enabledNow.add(id);
+		}
+		for (const id of disable) {
+			nextPatch = editCapabilityPatchLayer(nextPatch, id, false);
+			enabledNow.delete(id);
+		}
+		if (!existsSync(patchPath) || !patchText.includes("Written by dsh-plus start from the capability interview.")) {
+			const backup = patchPath + ".before-capabilities";
+			if (patchText !== "" && !existsSync(backup)) writeFileSync(backup, patchText);
+		}
+		writeFileSync(patchPath, nextPatch);
+		const nextEnv = capabilityEnvironment({
+			enabled: [...enabledNow],
+			...record?.mineruEndpoint === void 0 ? {} : { mineruEndpoint: record.mineruEndpoint }
+		}, envText);
+		writeFileSync(envPath, nextEnv);
+		const after = detectEnabledCapabilities(nextPatch, nextEnv);
+		console.log("Updated cordis.patch.yml and .env.");
+		console.log("Run dsh-plus start (or restart the server) to apply the change.");
+		return reportCapabilities(after, record, asJson);
+	}
+	return reportCapabilities(actual, record, asJson);
+}
+/**
+* Print the capability report.
+*
+* @param actual - the capabilities found in the profile layer and env file.
+* @param record - what the last configured run recorded, when a record exists.
+* @param asJson - when true, print machine-readable JSON instead of the table.
+* @returns the process exit code, always 0.
+*/
+function reportCapabilities(actual, record, asJson) {
+	const rows = CAPABILITIES.map((capability) => {
+		const mounted = actual.mounted.includes(capability.id);
+		const recorded = record?.enabled.includes(capability.id);
+		return {
+			id: capability.id,
+			title: capability.title,
+			enabled: mounted,
+			recorded: recorded ?? null
+		};
+	});
+	if (asJson) {
+		console.log(JSON.stringify({
+			capabilities: rows,
+			env: actual.env,
+			recordPresent: record !== void 0
+		}, null, 2));
+		return 0;
+	}
+	console.log("Optional capabilities:");
+	for (const row of rows) {
+		const state = row.enabled ? "enabled " : "disabled";
+		const drift = row.recorded !== null && row.recorded !== row.enabled ? "  (record says " + (row.recorded ? "enabled" : "disabled") + ")" : "";
+		console.log("  " + (row.enabled ? "ok  " : "--  ") + row.id.padEnd(14) + state + drift);
+	}
+	if (record === void 0) {
+		console.log("");
+		console.log("No capabilities.json yet; the next dsh-plus start will run the interview.");
+	}
+	console.log("");
+	console.log("Change with: dsh-plus capabilities --enable <id> | --disable <id>");
+	return 0;
+}
 async function doctor() {
 	const paths = resolvePaths(installationAnchor());
 	let failures = 0;
@@ -964,6 +1796,12 @@ async function doctor() {
 	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"));
+	const patchPath = join(paths.profileDirectory, CAPABILITY_PATCH_FILE);
+	const envPath = join(paths.home, CAPABILITY_ENV_FILE);
+	const actual = detectEnabledCapabilities(existsSync(patchPath) ? readFileSync(patchPath, "utf8") : "", existsSync(envPath) ? readFileSync(envPath, "utf8") : "");
+	const record = readCapabilityRecord(paths.home);
+	const drifted = record === void 0 ? [] : CAPABILITIES.filter((capability) => record.enabled.includes(capability.id) !== actual.mounted.includes(capability.id));
+	check(drifted.length === 0, drifted.length === 0 ? "capabilities: " + (actual.mounted.length === 0 ? "(none enabled)" : actual.mounted.join(", ")) : "capabilities disagree with capabilities.json: " + drifted.map((capability) => capability.id).join(", ") + " (run dsh-plus capabilities)");
 	console.log(failures === 0 ? "No problems found." : String(failures) + " problem(s) found.");
 	return failures === 0 ? 0 : 1;
 }
@@ -971,11 +1809,12 @@ 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         start the server (first run creates the profile)",
+	"  stop          stop the server",
+	"  status        report whether the server is running",
+	"  capabilities  report or change the optional capabilities",
+	"  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)",
@@ -983,6 +1822,11 @@ const USAGE = [
 	"  --no-open      do not open a browser",
 	"  --foreground   run in this terminal instead of in the background",
 	"",
+	"capabilities options:",
+	"  --enable <ids>   enable the comma-separated capability ids",
+	"  --disable <ids>  disable the comma-separated capability ids",
+	"  --json           print the report as JSON",
+	"",
 	"update options:",
 	"  --check        report the available release without installing it",
 	"  --yes          install without asking"
@@ -1002,6 +1846,7 @@ async function runStandaloneCli(argv) {
 	if (command === "start") return await start(rest);
 	if (command === "stop") return stop();
 	if (command === "status") return status();
+	if (command === "capabilities") return capabilities(rest);
 	if (command === "update") return await update(rest);
 	if (command === "doctor") return doctor();
 	console.error("unknown command: " + command);