@sparkelf/dsh-plus 0.2.0-rc.34 → 0.2.0-rc.36

package/lib/bin.js

@@ -160,15 +160,21 @@ async function interviewCapabilities(interactive) {
 		...mineruEndpoint === void 0 ? {} : { mineruEndpoint }
 	};
 }
-/** Names this module owns in the deployment env file. */
-const CAPABILITY_ENV_NAMES = ["DSH_MINERU_ENDPOINT", "EXA_API_KEY"];
+/**
+* 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.
 *
-* MinerU is switched on by the presence of its endpoint and 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
+* 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.
 *
@@ -179,13 +185,20 @@ const CAPABILITY_ENV_NAMES = ["DSH_MINERU_ENDPOINT", "EXA_API_KEY"];
 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("mineru")) written.push("DSH_MINERU_ENDPOINT=" + (answers.mineruEndpoint ?? "http://127.0.0.1:8000/file_parse"));
-	if (enabled.has("exa") && answers.exaApiKey !== void 0) written.push("EXA_API_KEY=" + answers.exaApiKey);
+	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";
 }
 /**
@@ -208,6 +221,8 @@ function capabilityPatchLayer(answers) {
 	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."];
 	if (rows.length > 0) lines.push("- insert:", ...rows);
 	else lines.push("[]");
@@ -219,6 +234,212 @@ 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
@@ -1388,6 +1609,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;
@@ -1400,6 +1749,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;
 }
@@ -1407,11 +1762,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)",
@@ -1419,6 +1775,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"
@@ -1438,6 +1799,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);

package/lib/types/standalone-capabilities.d.ts

@@ -66,9 +66,8 @@ export declare function interviewCapabilities(interactive: boolean): Promise<Cap
  * The deployment env file, with one assignment per enabled capability that reaches
  * its service through the launch environment.
  *
- * MinerU is switched on by the presence of its endpoint and 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
+ * 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.
  *
@@ -93,6 +92,52 @@ export declare function capabilityEnvironment(answers: CapabilityAnswers, existi
  * @returns the patch layer's YAML text.
  */
 export declare function capabilityPatchLayer(answers: CapabilityAnswers): string;
+/**
+ * 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.
+ */
+export declare function readCapabilityRecord(home: string): CapabilityAnswers | undefined;
+/**
+ * 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.
+ */
+export declare function detectEnabledCapabilities(profilePatchText: string, envText: string): {
+    readonly mounted: readonly string[];
+    readonly env: readonly string[];
+};
+/**
+ * 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.
+ */
+export declare function editCapabilityPatchLayer(existing: string, id: string, enable: boolean, mineruEndpoint?: string): string;
 /**
  * Install and start the backing services the selected capabilities need.
  *

package/lib/types/standalone-capabilities.js

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 /** Capabilities offered at install time, in interview order. */
 export const CAPABILITIES = [
@@ -96,15 +96,21 @@ export async function interviewCapabilities(interactive) {
         ...mineruEndpoint === undefined ? {} : { mineruEndpoint },
     };
 }
-/** Names this module owns in the deployment env file. */
-const CAPABILITY_ENV_NAMES = ['DSH_MINERU_ENDPOINT', 'EXA_API_KEY'];
+/**
+ * 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.
  *
- * MinerU is switched on by the presence of its endpoint and 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
+ * 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.
  *
@@ -115,6 +121,17 @@ const CAPABILITY_ENV_NAMES = ['DSH_MINERU_ENDPOINT', 'EXA_API_KEY'];
 export function capabilityEnvironment(answers, existing = '') {
     const enabled = new Set(answers.enabled);
     const owned = new Set(CAPABILITY_ENV_NAMES);
+    // Values the file already carries for the names this module owns. Re-running a
+    // configured start must not delete a credential the deployment already holds: the
+    // interview returns no key when the user says they will add it later, and enabling an
+    // unrelated capability still rewrites this whole file. Reading the present value back
+    // is what keeps `start` from undoing an earlier answer.
+    const carried = 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] !== undefined && 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 === undefined || !owned.has(name));
@@ -123,11 +140,10 @@ export function capabilityEnvironment(answers, existing = '') {
         '# 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('mineru')) {
-        written.push('DSH_MINERU_ENDPOINT=' + (answers.mineruEndpoint ?? DEFAULT_MINERU_ENDPOINT));
-    }
-    if (enabled.has('exa') && answers.exaApiKey !== undefined) {
-        written.push('EXA_API_KEY=' + answers.exaApiKey);
+    if (enabled.has('exa')) {
+        const key = answers.exaApiKey ?? carried.get('EXA_API_KEY');
+        if (key !== undefined && key !== '')
+            written.push('EXA_API_KEY=' + key);
     }
     return [...written, ...kept].join('\n') + '\n';
 }
@@ -155,6 +171,20 @@ export function capabilityPatchLayer(answers) {
     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')) {
+        // The plugin ships inside the mounted bundle and carries its own binary, so the
+        // capability needs no host step — but a selection that writes no row mounts nothing,
+        // and the capability then reports as ready while the tools stay absent. The row id
+        // and package match the plugin's own bundle layer.
+        rows.push('    - id: officecli', "      name: '@sparkelf/dsh-officecli'");
+    }
+    // MinerU reads its endpoint from plugin config, not from the environment, and a name prefixed
+    // `DSH_` is refused in any .env file because `DSH_HOME` is itself bootstrap-only — the file could
+    // otherwise relocate the home it is read from. Writing the endpoint as a profile row is both the
+    // plugin's own contract and the only place the loader accepts it.
+    if (enabled.has('mineru')) {
+        rows.push('    - id: mineru', "      name: '@sparkelf/dsh-mineru'", '      config:', '        endpoint: ' + (answers.mineruEndpoint ?? DEFAULT_MINERU_ENDPOINT));
+    }
     const lines = [
         '# ' + CAPABILITY_MARKER + ' Enabling or disabling a capability',
         '# rewrites this file; edits here are replaced.',
@@ -179,6 +209,266 @@ function runStep(command, args) {
     const result = spawnSync(command, [...args], { stdio: 'inherit' });
     return result.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.
+ */
+export function readCapabilityRecord(home) {
+    const path = join(home, CAPABILITY_RECORD);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        // Absent and unreadable are the same answer here: the caller falls back to the
+        // profile and env files, which are the authoritative state a record only mirrors.
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    if (!Array.isArray(record.enabled))
+        return undefined;
+    const enabled = record.enabled.filter((id) => typeof id === 'string');
+    return {
+        enabled,
+        ...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.
+ */
+export function detectEnabledCapabilities(profilePatchText, envText) {
+    const mounted = [];
+    // Matching the row id is what the loader does; matching a bare package name would also
+    // hit a comment or a name mentioned in an unrelated row's config.
+    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 !== undefined && !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'",
+        ];
+    }
+    return undefined;
+}
+/** 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.
+ */
+export function editCapabilityPatchLayer(existing, id, enable, mineruEndpoint) {
+    const owned = capabilityRowIds(id);
+    const withoutRows = dropOwnedRows(existing, owned, id === 'exa');
+    const mineruRows = [
+        '    - id: mineru',
+        "      name: '@sparkelf/dsh-mineru'",
+        '      config:',
+        '        endpoint: ' + (mineruEndpoint ?? DEFAULT_MINERU_ENDPOINT),
+    ];
+    const rows = id === 'mineru' && enable ? mineruRows : capabilityRows(id);
+    const text = enable && rows !== undefined
+        ? insertCapabilityRows(withoutRows, rows, id === 'exa')
+        : withoutRows.text;
+    // Every file this repository writes ends with exactly one newline; an edited layer must
+    // not lose that, and the loader's YAML parse is indifferent to it either way.
+    const trimmed = 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);
+        // The `web` selector is shared with the built-in provider: dropping it turns Exa off
+        // without touching the row's other keys, because the bundle layer's row reapplies.
+        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] ?? '';
+        // Drop the comments that documented this row, stopping at a blank line so an unrelated
+        // comment above a blank line is not consumed.
+        while (out.length > 0) {
+            const previous = out[out.length - 1] ?? '';
+            if (previous.trimStart().startsWith('#') && previous.trim() !== '')
+                out.pop();
+            else
+                break;
+        }
+        // Then the row's own continuation lines: deeper-indented or blank lines until the next
+        // entry at the same or a shallower level.
+        for (index += 1; index < lines.length; index += 1) {
+            const next = lines[index] ?? '';
+            if (next.trim() === '') {
+                // A blank line inside a row's block keeps it; a blank line starting a new block
+                // belongs to the file's spacing and goes back.
+                const after = lines[index + 1] ?? '';
+                if (after !== '' && (after.startsWith(indent + ' ') || after.startsWith(indent + '\t') || after.trimStart().startsWith('#'))) {
+                    continue;
+                }
+                index -= 1;
+                break;
+            }
+            const nextIndent = /^\s*/.exec(next)?.[0] ?? '';
+            if (nextIndent.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) {
+        // Append at the end of the existing insert block: walk past its payload lines.
+        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 {
+        // A layer with no entries is the literal `[]`; replacing it keeps one valid array.
+        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() ?? '' : undefined;
+            lines.push('- insert:', ...rows);
+            if (trailing !== undefined)
+                lines.push(trailing);
+        }
+    }
+    if (withSelector && !/^\s*- id: web\s*$/mu.test(lines.join('\n'))) {
+        // The selector is a top-level row: it patches the bundle layer's own `web` entry, and
+        // it must restate `fetchProvider` because a patch replaces the whole `config` object
+        // rather than merging into it.
+        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.
  *

package/lib/types/standalone-cli.js

@@ -13,7 +13,7 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { newerVersion } from "./registry-versions.js";
-import { CAPABILITIES, CAPABILITY_ENV_FILE, CAPABILITY_MARKER, CAPABILITY_RECORD, DEFAULT_MINERU_ENDPOINT, capabilityEnvironment, capabilityPatchLayer, installCapabilityServices, interviewCapabilities, } from "./standalone-capabilities.js";
+import { CAPABILITIES, CAPABILITY_ENV_FILE, CAPABILITY_MARKER, CAPABILITY_RECORD, DEFAULT_MINERU_ENDPOINT, capabilityEnvironment, capabilityPatchLayer, detectEnabledCapabilities, editCapabilityPatchLayer, installCapabilityServices, interviewCapabilities, readCapabilityRecord, } from "./standalone-capabilities.js";
 import { DEFAULT_PORT, STOP_GRACE_MILLISECONDS, choosePort, clearState, isRunning, portAvailable, readState, spawnServer, stateDirectory, waitForAuthenticatedUrl, waitForServer, writeState, } from "./standalone-server.js";
 import { STANDALONE_PROFILE, applyProfileNpmPatches, ensureProfile, pnpmAvailable, pnpmInstallCommand, pnpmInstallCommands, registryOrder, readDistributionProfile, resolvePaths, } from "./standalone-profile.js";
 /** Milliseconds a start waits for the server to answer before reporting failure. */
@@ -414,6 +414,140 @@ 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 anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    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 === undefined || 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(CAPABILITY_MARKER)) {
+            // The layer belongs to the deployment, not to this command. Keep the previous text
+            // beside it so a structural mistake is recoverable without a backup.
+            const backup = patchPath + '.before-capabilities';
+            if (patchText !== '' && !existsSync(backup))
+                writeFileSync(backup, patchText);
+        }
+        writeFileSync(patchPath, nextPatch);
+        // The env file is rewritten from the answers so a disabled capability drops the
+        // assignment that turned it on, and an enabled one keeps a key already in the file.
+        const answers = {
+            enabled: [...enabledNow],
+            ...record?.mineruEndpoint === undefined ? {} : { mineruEndpoint: record.mineruEndpoint },
+        };
+        const nextEnv = capabilityEnvironment(answers, envText);
+        writeFileSync(envPath, nextEnv);
+        const after = detectEnabledCapabilities(nextPatch, nextEnv);
+        console.log('Updated ' + CAPABILITY_PATCH_FILE + ' and ' + CAPABILITY_ENV_FILE + '.');
+        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 !== undefined,
+        }, null, 2));
+        return 0;
+    }
+    console.log('Optional capabilities:');
+    for (const row of rows) {
+        const state = row.enabled ? 'enabled ' : 'disabled';
+        // A record that disagrees with the files is the one case worth calling out: the two
+        // are supposed to describe the same deployment.
+        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 === undefined) {
+        console.log('');
+        console.log('No ' + CAPABILITY_RECORD + ' 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 anchor = installationAnchor();
     const paths = resolvePaths(anchor);
@@ -429,6 +563,21 @@ 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'));
+    // The capability record and the files that actually enable a capability are written by
+    // different runs, so they can disagree: a layer edited by hand, or a record deleted.
+    // Reporting the drift here is what turns the record from a write-only file into
+    // something a user can trust.
+    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 === undefined
+        ? []
+        : 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 ' + CAPABILITY_RECORD + ': ' + 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;
 }
@@ -436,11 +585,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)',
@@ -448,6 +598,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',
@@ -470,6 +625,8 @@ export async function runStandaloneCli(argv) {
         return stop();
     if (command === 'status')
         return status();
+    if (command === 'capabilities')
+        return capabilities(rest);
     if (command === 'update')
         return await update(rest);
     if (command === 'doctor')

package/package.json

@@ -217,5 +217,5 @@
   },
   "type": "module",
   "types": "lib/types/index.d.ts",
-  "version": "0.2.0-rc.34"
+  "version": "0.2.0-rc.36"
 }