dsh-web-search-pro 0.2.0 → 0.2.1

package/lib/client.js

@@ -779,6 +779,8 @@ window.__ModuleLoader__.load({
 			jsonField("platformRules"),
 			jsonField("customPlatforms"),
 			jsonField("browserBindings"),
+			jsonField("platformBackends"),
+			jsonField("cliAdapters"),
 			booleanField("verbose")
 		];
 		/** The effective judge mode: the neutral `judge.mode` wins over the legacy `jevMode`. */
@@ -1008,6 +1010,1384 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region src/cli/spec.ts
+		/**
+		* Declarative CLI adapter spec (dev-plan M12): what a standalone command-line tool is, which of its commands the plugin
+		* may run, and how its output maps to search sources. Pure data plus validation, no Node imports, so the settings card
+		* (client bundle) validates `cliAdapters` with the very function the server uses.
+		*
+		* The read-only guarantee lives here and applies to built-in and user-defined specs alike:
+		*  - argv is an array of tokens, never a shell string (the runner spawns without a shell);
+		*  - a spec declares `allowedSubcommands`, and every command word its argv uses (the leading literal tokens before the
+		*    first flag or placeholder) must be in that list;
+		*  - no command word, declared subcommand or flag may match the global deny-list (login, post, delete*, like, ...,
+		*    and the flags that make a CLI read browser cookies or carry secrets in argv).
+		* @module web-search-pro/cli/spec
+		*/
+		const OUTPUT_FORMATS = [
+			"json",
+			"ndjson",
+			"yaml",
+			"text"
+		];
+		/** How far a spec has been checked against the real tool (recorded in the spec and shown in `sources.status`). */
+		const CLI_VERIFICATIONS = [
+			"live",
+			"contract-only",
+			"docs-only"
+		];
+		/** Command words that write, log in, or change local or remote state. Matched exactly, or as `<word>-...` / `<word>_...`. */
+		const DENIED_SUBCOMMANDS = [
+			"login",
+			"logout",
+			"signin",
+			"signout",
+			"sign-in",
+			"sign-out",
+			"auth",
+			"whoami-login",
+			"post",
+			"comment",
+			"reply",
+			"publish",
+			"ask",
+			"article",
+			"pin",
+			"draft",
+			"upload",
+			"send",
+			"create",
+			"edit",
+			"write",
+			"add",
+			"like",
+			"unlike",
+			"dislike",
+			"upvote",
+			"downvote",
+			"vote",
+			"follow",
+			"unfollow",
+			"subscribe",
+			"unsubscribe",
+			"favorite",
+			"unfavorite",
+			"bookmark",
+			"unbookmark",
+			"save",
+			"unsave",
+			"retweet",
+			"unretweet",
+			"quote",
+			"share",
+			"block",
+			"unblock",
+			"mute",
+			"accept",
+			"forward",
+			"setup",
+			"init",
+			"install",
+			"uninstall",
+			"update",
+			"upgrade",
+			"config",
+			"configure",
+			"register",
+			"set",
+			"import",
+			"export",
+			"bridge",
+			"daemon",
+			"plugin",
+			"adapter",
+			"external",
+			"profile",
+			"mcp",
+			"serve"
+		];
+		/** Command words denied by prefix alone (`delete`, `delete-note`, `deleteNote`, `remove...`). */
+		const DENIED_PREFIXES = [
+			"delete",
+			"remove",
+			"destroy",
+			"drop",
+			"purge",
+			"revoke"
+		];
+		/** Flags (without leading dashes) that read browser cookies or carry credentials in argv. */
+		const DENIED_FLAGS = [
+			"cookie-source",
+			"cookie",
+			"cookies",
+			"cookies-from-browser",
+			"browser-cookies",
+			"from-browser",
+			"browser",
+			"password",
+			"passwd",
+			"secret",
+			"token",
+			"access-token",
+			"auth-token",
+			"api-key",
+			"apikey",
+			"key",
+			"username",
+			"user-token",
+			"ap-password",
+			"netrc",
+			"client-secret",
+			"authorization",
+			"auth"
+		];
+		function matchesDeniedSubcommand(word) {
+			const w = word.toLowerCase();
+			if (DENIED_PREFIXES.some((prefix) => w.startsWith(prefix))) return true;
+			return DENIED_SUBCOMMANDS.some((denied) => w === denied || w.startsWith(denied + "-") || w.startsWith(denied + "_"));
+		}
+		const flagName = (token) => token.replace(/^-+/, "").split("=")[0].toLowerCase();
+		const isFlag = (token) => token.startsWith("-") && token.length > 1;
+		const hasPlaceholder = (token) => /\{[A-Za-z0-9_.]+\}/.test(token);
+		/** The command words of an argv: leading literal tokens before the first flag or placeholder token. */
+		function commandWords(argv) {
+			const words = [];
+			for (const token of argv) {
+				if (isFlag(token) || hasPlaceholder(token)) break;
+				words.push(token);
+			}
+			return words;
+		}
+		/** Problems of one argv template with respect to the read-only guard (empty = fine). */
+		function argvProblems(argv, allowed, where) {
+			const problems = [];
+			for (const word of commandWords(argv)) if (matchesDeniedSubcommand(word)) problems.push(where + ": \"" + word + "\" is a write / login command (read-only guard)");
+			else if (!allowed.includes(word)) problems.push(where + ": command word \"" + word + "\" is not in allowedSubcommands");
+			for (const token of argv) if (isFlag(token) && DENIED_FLAGS.includes(flagName(token))) problems.push(where + ": flag \"" + token + "\" reads cookies or carries credentials (read-only guard)");
+			return problems;
+		}
+		const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+		const isStr = (v, max = 200) => typeof v === "string" && v.length > 0 && v.length <= max;
+		const strList = (v, maxItems, maxLen = 200) => Array.isArray(v) && v.length <= maxItems && v.every((x) => isStr(x, maxLen));
+		const ID_RE = /^[a-z0-9][a-z0-9._-]{0,39}$/;
+		const BIN_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+		const ENV_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+		const PATH_RE = /^[A-Za-z0-9_$-]+(\.[A-Za-z0-9_$-]+)*$/;
+		const VERSION_RE = /^\d+(\.\d+){0,3}$/;
+		const PLACEHOLDERS = /* @__PURE__ */ new Set([
+			"query",
+			"count",
+			"url"
+		]);
+		const MAX_TIMEOUT_MS = 18e4;
+		const MAX_OUTPUT_BYTES = 16777216;
+		const SPEC_KEYS = /* @__PURE__ */ new Set([
+			"id",
+			"bins",
+			"packageNote",
+			"platforms",
+			"probe",
+			"allowedSubcommands",
+			"search",
+			"searches",
+			"read",
+			"env",
+			"needsLogin",
+			"login",
+			"timeoutMs",
+			"maxOutputBytes",
+			"verification"
+		]);
+		const PROBE_KEYS = /* @__PURE__ */ new Set([
+			"versionArgs",
+			"minVersion",
+			"helpArgs",
+			"mustContain"
+		]);
+		const SEARCH_KEYS = /* @__PURE__ */ new Set([
+			"argv",
+			"maxCount",
+			"output",
+			"emptyWhen",
+			"notLoggedInPatterns"
+		]);
+		const OUTPUT_KEYS = /* @__PURE__ */ new Set([
+			"format",
+			"itemsPath",
+			"expect",
+			"errorPaths",
+			"lines",
+			"fields",
+			"stripTags",
+			"emptyValues",
+			"snippetMax",
+			"titleMax",
+			"requireTitle"
+		]);
+		const FIELD_KEYS = /* @__PURE__ */ new Set([
+			"url",
+			"title",
+			"snippet",
+			"publishedAt"
+		]);
+		const ENV_KEYS = /* @__PURE__ */ new Set([
+			"required",
+			"passthrough",
+			"set"
+		]);
+		const LOGIN_KEYS = /* @__PURE__ */ new Set([
+			"command",
+			"savedCredentialPaths",
+			"readsBrowserCookiesWithoutLogin"
+		]);
+		function closed(obj, keys, where, errors) {
+			for (const key of Object.keys(obj)) if (!keys.has(key)) errors.push(where + "." + key + " is not a spec field");
+		}
+		function templateProblems(text, where, allowedPlaceholders, errors) {
+			for (const match of text.matchAll(/\{([^}]*)\}/g)) {
+				const name = match[1];
+				if (allowedPlaceholders ? !allowedPlaceholders.has(name) : !PATH_RE.test(name)) errors.push(where + ": unknown placeholder {" + name + "}");
+			}
+			if (/\{[^}]*$/.test(text) || /^[^{]*\}/.test(text)) errors.push(where + ": unbalanced brace");
+		}
+		function checkFieldSource(value, where, errors) {
+			if (typeof value === "string") {
+				if (!PATH_RE.test(value)) errors.push(where + ": \"" + value + "\" is not a dotted path");
+				return;
+			}
+			if (Array.isArray(value)) {
+				if (!value.length || value.length > 12) errors.push(where + ": a source list needs 1..12 entries");
+				for (const entry of value) if (typeof entry === "string") {
+					if (!PATH_RE.test(entry)) errors.push(where + ": \"" + entry + "\" is not a dotted path");
+				} else if (isObject(entry) && typeof entry.template === "string") checkFieldSource(entry, where, errors);
+				else errors.push(where + ": list entries are paths or { template, when? }");
+				return;
+			}
+			if (!isObject(value)) {
+				errors.push(where + " must be a path, a list, { template }, { join }, { epoch } or { date }");
+				return;
+			}
+			const keys = Object.keys(value);
+			if (keys.length === 1 && (keys[0] === "epoch" || keys[0] === "date")) {
+				if (typeof value[keys[0]] !== "string" || !PATH_RE.test(value[keys[0]])) errors.push(where + "." + keys[0] + " must be a dotted path");
+				return;
+			}
+			if (keys.every((k) => k === "template" || k === "when") && "template" in value) {
+				if (!isStr(value.template, 300)) errors.push(where + ".template must be a string");
+				else templateProblems(value.template, where + ".template", void 0, errors);
+				if (value.when !== void 0) {
+					const w = value.when;
+					if (!(isObject(w) && typeof w.path === "string" && PATH_RE.test(w.path) && [
+						"string",
+						"number",
+						"boolean"
+					].includes(typeof w.equals) && Object.keys(w).every((k) => k === "path" || k === "equals"))) errors.push(where + ".when must be { path, equals }");
+				}
+				return;
+			}
+			if (keys.every((k) => k === "join" || k === "sep") && Array.isArray(value.join)) {
+				if (!value.join.length || value.join.length > 8) errors.push(where + ".join needs 1..8 parts");
+				for (const part of value.join) if (typeof part === "string") {
+					if (!PATH_RE.test(part)) errors.push(where + ".join: \"" + part + "\" is not a dotted path");
+				} else if (isObject(part) && typeof part.path === "string" && PATH_RE.test(part.path) && Object.keys(part).every((k) => [
+					"path",
+					"prefix",
+					"suffix"
+				].includes(k))) {
+					for (const k of ["prefix", "suffix"]) if (part[k] !== void 0 && !(typeof part[k] === "string" && part[k].length <= 40)) errors.push(where + ".join." + k + " must be a short string");
+				} else errors.push(where + ".join: each part is a path or { path, prefix?, suffix? }");
+				if (value.sep !== void 0 && !(typeof value.sep === "string" && value.sep.length <= 16)) errors.push(where + ".sep must be a short string");
+				return;
+			}
+			errors.push(where + " must be a path, a list, { template }, { join }, { epoch } or { date }");
+		}
+		function checkOutput(value, where, errors) {
+			if (!isObject(value)) {
+				errors.push(where + " must be an object");
+				return;
+			}
+			closed(value, OUTPUT_KEYS, where, errors);
+			if (!OUTPUT_FORMATS.includes(value.format)) errors.push(where + ".format must be one of " + OUTPUT_FORMATS.join("|"));
+			if (value.itemsPath !== void 0 && !(typeof value.itemsPath === "string" && PATH_RE.test(value.itemsPath))) errors.push(where + ".itemsPath must be a dotted path");
+			if (value.expect !== void 0) {
+				if (!Array.isArray(value.expect) || value.expect.length > 8) errors.push(where + ".expect must be a list of { path, equals }");
+				else for (const e of value.expect) if (!(isObject(e) && typeof e.path === "string" && PATH_RE.test(e.path) && [
+					"string",
+					"number",
+					"boolean"
+				].includes(typeof e.equals) && Object.keys(e).every((k) => k === "path" || k === "equals"))) errors.push(where + ".expect entries are { path, equals }");
+			}
+			if (value.errorPaths !== void 0 && !(Array.isArray(value.errorPaths) && value.errorPaths.length <= 6 && value.errorPaths.every((p) => typeof p === "string" && PATH_RE.test(p)))) errors.push(where + ".errorPaths must be dotted paths");
+			if (value.lines !== void 0) {
+				const l = value.lines;
+				if (isObject(l) && l.mode === "url-lines" && Object.keys(l).length === 1) {} else if (isObject(l) && l.mode === "tsv" && strList(l.columns, 24, 40) && l.columns.length >= 2 && l.columns.every((c) => /^[A-Za-z0-9_]+$/.test(c)) && Object.keys(l).every((k) => k === "mode" || k === "columns")) {} else errors.push(where + ".lines must be { mode: \"url-lines\" } or { mode: \"tsv\", columns: [...] }");
+			}
+			if (value.format === "text" && value.lines === void 0) errors.push(where + ".lines is required for format text");
+			if (value.format !== "text" && value.lines !== void 0) errors.push(where + ".lines is only for format text");
+			if (!isObject(value.fields)) errors.push(where + ".fields must be an object");
+			else {
+				closed(value.fields, FIELD_KEYS, where + ".fields", errors);
+				if (value.fields.url === void 0) errors.push(where + ".fields.url is required");
+				for (const key of Object.keys(value.fields)) if (FIELD_KEYS.has(key)) checkFieldSource(value.fields[key], where + ".fields." + key, errors);
+			}
+			if (value.stripTags !== void 0 && typeof value.stripTags !== "boolean") errors.push(where + ".stripTags must be a boolean");
+			if (value.emptyValues !== void 0 && !strList(value.emptyValues, 8, 20)) errors.push(where + ".emptyValues must be short strings");
+			for (const key of ["snippetMax", "titleMax"]) if (value[key] !== void 0 && !(Number.isInteger(value[key]) && value[key] >= 40 && value[key] <= 2e3)) errors.push(where + "." + key + " must be an integer 40..2000");
+			if (value.requireTitle !== void 0 && typeof value.requireTitle !== "boolean") errors.push(where + ".requireTitle must be a boolean");
+		}
+		function checkSearch(value, where, allowed, errors) {
+			if (!isObject(value)) {
+				errors.push(where + " must be an object");
+				return;
+			}
+			closed(value, SEARCH_KEYS, where, errors);
+			if (!Array.isArray(value.argv) || !value.argv.length || value.argv.length > 24 || !value.argv.every((t) => typeof t === "string" && t.length > 0 && t.length <= 200)) errors.push(where + ".argv must be an array of 1..24 non-empty strings (never a shell string)");
+			else {
+				const argv = value.argv;
+				argv.forEach((token) => templateProblems(token, where + ".argv", PLACEHOLDERS, errors));
+				if (!argv.some((t) => /\{(query|url)\}/.test(t))) errors.push(where + ".argv must carry a {query} (or {url}) placeholder");
+				errors.push(...argvProblems(argv, allowed, where + ".argv"));
+			}
+			if (value.maxCount !== void 0 && !(Number.isInteger(value.maxCount) && value.maxCount >= 1 && value.maxCount <= 100)) errors.push(where + ".maxCount must be an integer 1..100");
+			checkOutput(value.output, where + ".output", errors);
+			for (const key of ["emptyWhen", "notLoggedInPatterns"]) if (value[key] !== void 0 && !strList(value[key], 12, 120)) errors.push(where + "." + key + " must be a list of short strings");
+		}
+		/**
+		* Validate one adapter spec (built-in or user-defined). Never throws. A user-defined spec (`origin: 'user'`) may not carry a
+		* `verification` (it is unverified by definition) and its `platforms` are ignored: it is registered as `custom-cli:<id>`.
+		*/
+		function validateCliAdapterSpec(raw, origin = "user") {
+			const errors = [];
+			if (!isObject(raw)) return {
+				ok: false,
+				errors: ["spec must be an object"]
+			};
+			const at = "cliAdapters." + (typeof raw.id === "string" ? raw.id : "(no id)");
+			closed(raw, SPEC_KEYS, at, errors);
+			if (typeof raw.id !== "string" || !ID_RE.test(raw.id)) errors.push(at + ".id must match " + String(ID_RE));
+			if (!Array.isArray(raw.bins) || !raw.bins.length || raw.bins.length > 4 || !raw.bins.every((b) => typeof b === "string" && BIN_RE.test(b))) errors.push(at + ".bins must be 1..4 command names (no paths)");
+			if (!isStr(raw.packageNote, 240)) errors.push(at + ".packageNote must be a short string (what the package is called, which can differ from the command)");
+			if (!strList(raw.platforms, 8, 40) || !raw.platforms.length) errors.push(at + ".platforms must list 1..8 platform ids");
+			if (typeof raw.needsLogin !== "boolean") errors.push(at + ".needsLogin must be a boolean");
+			if (!(Number.isInteger(raw.timeoutMs) && raw.timeoutMs >= 1e3 && raw.timeoutMs <= MAX_TIMEOUT_MS)) errors.push(at + ".timeoutMs must be an integer 1000..180000");
+			if (!(Number.isInteger(raw.maxOutputBytes) && raw.maxOutputBytes >= 1024 && raw.maxOutputBytes <= MAX_OUTPUT_BYTES)) errors.push(at + ".maxOutputBytes must be an integer 1024..16777216");
+			const allowed = strList(raw.allowedSubcommands, 12, 60) ? raw.allowedSubcommands : void 0;
+			if (!allowed) errors.push(at + ".allowedSubcommands must list the command words the spec uses (up to 12; empty for a tool without subcommands)");
+			else for (const word of allowed) if (matchesDeniedSubcommand(word)) errors.push(at + ".allowedSubcommands: \"" + word + "\" is a write / login command (read-only guard)");
+			if (!isObject(raw.probe)) errors.push(at + ".probe must be an object");
+			else {
+				const p = raw.probe;
+				closed(p, PROBE_KEYS, at + ".probe", errors);
+				for (const key of ["versionArgs", "helpArgs"]) if (!Array.isArray(p[key]) || !p[key].every((t) => typeof t === "string" && t.length > 0 && t.length <= 80) || p[key].length > 6) errors.push(at + ".probe." + key + " must be an array of short strings");
+				else if (allowed) errors.push(...argvProblems(p[key], allowed, at + ".probe." + key));
+				if (!(Array.isArray(p.helpArgs) && p.helpArgs.length)) errors.push(at + ".probe.helpArgs must not be empty");
+				if (p.minVersion !== void 0 && !(typeof p.minVersion === "string" && VERSION_RE.test(p.minVersion))) errors.push(at + ".probe.minVersion must look like 1.2.3");
+				if (!strList(p.mustContain, 12, 80)) errors.push(at + ".probe.mustContain must be a list of short strings (the subcommands / flags that prove the contract)");
+			}
+			const searchWhere = (key) => at + "." + key;
+			if (allowed) {
+				checkSearch(raw.search, searchWhere("search"), allowed, errors);
+				if (raw.searches !== void 0) {
+					if (!isObject(raw.searches)) errors.push(at + ".searches must be an object keyed by platform id");
+					else for (const [platform, s] of Object.entries(raw.searches)) {
+						if (!ID_RE.test(platform)) errors.push(at + ".searches: \"" + platform + "\" is not a platform id");
+						checkSearch(s, at + ".searches." + platform, allowed, errors);
+					}
+				}
+				if (raw.read !== void 0) checkSearch(raw.read, searchWhere("read"), allowed, errors);
+			}
+			if (!isObject(raw.env)) errors.push(at + ".env must be an object");
+			else {
+				closed(raw.env, ENV_KEYS, at + ".env", errors);
+				for (const key of ["required", "passthrough"]) {
+					const list = raw.env[key];
+					if (list !== void 0 && !(Array.isArray(list) && list.length <= 16 && list.every((n) => typeof n === "string" && ENV_RE.test(n)))) errors.push(at + ".env." + key + " must be environment variable NAMES (never values)");
+				}
+				if (raw.env.set !== void 0) {
+					const set = raw.env.set;
+					if (!isObject(set) || Object.keys(set).length > 8 || !Object.entries(set).every(([k, val]) => ENV_RE.test(k) && typeof val === "string" && val.length <= 80)) errors.push(at + ".env.set must be a few NAME: short literal pairs");
+					else if (Object.keys(set).some((k) => /key|token|secret|password|cookie/i.test(k))) errors.push(at + ".env.set must not set credentials: name them in env.required / env.passthrough and keep the value in your environment");
+				}
+			}
+			if (raw.login !== void 0) {
+				const l = raw.login;
+				if (!isObject(l)) errors.push(at + ".login must be an object");
+				else {
+					closed(l, LOGIN_KEYS, at + ".login", errors);
+					if (!isStr(l.command, 120)) errors.push(at + ".login.command must be a short string (what the user runs themselves)");
+					if (l.savedCredentialPaths !== void 0 && !(strList(l.savedCredentialPaths, 4, 160) && l.savedCredentialPaths.every((p) => /^~\/[^\0]+$/.test(p) && !p.includes("..")))) errors.push(at + ".login.savedCredentialPaths must be paths starting with ~/ (no ..)");
+					if (l.readsBrowserCookiesWithoutLogin !== void 0 && typeof l.readsBrowserCookiesWithoutLogin !== "boolean") errors.push(at + ".login.readsBrowserCookiesWithoutLogin must be a boolean");
+					if (l.readsBrowserCookiesWithoutLogin === true && !(Array.isArray(l.savedCredentialPaths) && l.savedCredentialPaths.length)) errors.push(at + ".login: a tool that reads browser cookies without a login needs savedCredentialPaths, so the plugin can refuse to run it without one");
+				}
+			}
+			if (raw.needsLogin === true && !isObject(raw.login) && !(isObject(raw.env) && Array.isArray(raw.env.required) && raw.env.required.length)) errors.push(at + ": needsLogin without login.command or env.required gives the user nothing to run");
+			if (raw.verification !== void 0) {
+				const v = raw.verification;
+				if (origin === "user") errors.push(at + ".verification is for built-in specs only");
+				else if (!(isObject(v) && CLI_VERIFICATIONS.includes(v.status) && Object.keys(v).every((k) => [
+					"status",
+					"version",
+					"date",
+					"note"
+				].includes(k)))) errors.push(at + ".verification must be { status, version?, date?, note? }");
+				else if (v.status === "live" && !(isStr(v.version, 40) && typeof v.date === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v.date))) errors.push(at + ".verification: live needs the verified version and a YYYY-MM-DD date");
+			}
+			if (errors.length) return {
+				ok: false,
+				errors
+			};
+			return {
+				ok: true,
+				errors: [],
+				spec: raw
+			};
+		}
+		/** Validate the `cliAdapters` setting: the valid specs by id and the problems of the rest (an invalid entry is ignored, never fatal). */
+		function resolveCliAdapters(input) {
+			const specs = /* @__PURE__ */ new Map();
+			const diagnostics = [];
+			if (input === void 0 || input === null) return {
+				specs,
+				diagnostics
+			};
+			if (!isObject(input)) return {
+				specs,
+				diagnostics: ["cliAdapters must be an object keyed by adapter id"]
+			};
+			for (const [key, raw] of Object.entries(input)) {
+				if (isObject(raw) && raw.id !== void 0 && raw.id !== key) {
+					diagnostics.push("cliAdapters." + key + " ignored: its id \"" + String(raw.id) + "\" must equal its key");
+					continue;
+				}
+				const result = validateCliAdapterSpec(isObject(raw) ? {
+					...raw,
+					id: key
+				} : raw, "user");
+				if (!result.ok) {
+					diagnostics.push("cliAdapters." + key + " ignored: " + result.errors.slice(0, 4).join("; ") + (result.errors.length > 4 ? " (+" + (result.errors.length - 4) + " more)" : ""));
+					continue;
+				}
+				specs.set(key, result.spec);
+			}
+			return {
+				specs,
+				diagnostics
+			};
+		}
+		/** `platformBackends`: ordered backend ids per platform. Pure shape check; ids are checked against the known backends by the caller. */
+		function platformBackendProblems(input) {
+			if (input === void 0 || input === null) return [];
+			if (!isObject(input)) return ["platformBackends must be an object: { <platform>: [backend ids] }"];
+			const problems = [];
+			for (const [platform, ids] of Object.entries(input)) {
+				if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,59}$/.test(platform)) problems.push("platformBackends: \"" + platform + "\" is not a platform id");
+				if (!(Array.isArray(ids) && ids.length <= 12 && ids.every((id) => typeof id === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,59}$/.test(id)))) problems.push("platformBackends." + platform + " must be a list of backend ids");
+				else if (new Set(ids).size !== ids.length) problems.push("platformBackends." + platform + " lists a backend twice");
+			}
+			return problems;
+		}
+		//#endregion
+		//#region src/cli/builtin-specs.ts
+		/**
+		* The built-in CLI adapter specs (dev-plan M12). Every argv, flag and output field was derived from the tool's own
+		* `--help` (and, where the help does not show the output shape, from the installed package source or the upstream
+		* README), and `verification` records how far each was checked:
+		*  - `live`: a real read-only search was run and its output parsed (bili, gh, omnireach/wechat);
+		*  - `contract-only`: help and version probed on a real install, output shape taken from the tool's own source,
+		*    README or documented output option, because a search needs the user's login or reads browser cookies, or was outside
+		*    the checks allowed (xhs, zhihu, rdt, twitter, opencli sites, yt-dlp, wx-search-cli);
+		*  - `docs-only`: not installed here; derived from the upstream README (tanso).
+		* Fixtures for the contract-only and docs-only parsers are marked "constructed from help/docs" in test/fixtures/cli.
+		* @module web-search-pro/cli/builtin-specs
+		*/
+		const BILI_CLI_VERSION = "0.6.2";
+		const BILI_CLI_SOURCE = `git+https://github.com/public-clis/bilibili-cli@489607468f967e0e11f3cdff6efc022d011e982a`;
+		`${BILI_CLI_SOURCE}`, `${BILI_CLI_SOURCE}`, `${BILI_CLI_SOURCE}`;
+		/** The date of the checks recorded below. */
+		const SPEC_CHECK_DATE = "2026-10-06";
+		const MB = 1048576;
+		/** The versioned `{ ok, schema_version, data }` envelope of the agent-friendly Python CLIs (bili, xhs, rdt). */
+		const ENVELOPE = [{
+			path: "ok",
+			equals: true
+		}, {
+			path: "schema_version",
+			equals: "1"
+		}];
+		/** Why a login-needing CLI is gated on its saved login files: it reads the browser's cookies by itself when it has none. */
+		const NOT_LOGGED_IN = [
+			"not authenticated",
+			"not_authenticated",
+			"not logged in",
+			"login required",
+			"please log in",
+			"no 'a1' cookie",
+			"no cookies"
+		];
+		const bili = {
+			id: "bili",
+			bins: ["bili"],
+			packageNote: `bilibili-cli from public-clis/bilibili-cli ${BILI_CLI_VERSION} (the PyPI package of the same name has another contract; sources.deps shows the pinned install)`,
+			platforms: ["bilibili"],
+			probe: {
+				versionArgs: ["--version"],
+				minVersion: BILI_CLI_VERSION,
+				helpArgs: ["search", "--help"],
+				mustContain: [
+					"--type",
+					"--max",
+					"--json"
+				]
+			},
+			allowedSubcommands: ["search"],
+			search: {
+				argv: [
+					"search",
+					"{query}",
+					"--type",
+					"video",
+					"--max",
+					"{count}",
+					"--json"
+				],
+				maxCount: 10,
+				output: {
+					format: "json",
+					itemsPath: "data",
+					expect: ENVELOPE,
+					errorPaths: ["message", "error"],
+					stripTags: true,
+					snippetMax: 300,
+					fields: {
+						url: [
+							{ template: "https://www.bilibili.com/video/{bvid}" },
+							"url",
+							"link",
+							"arcurl"
+						],
+						title: "title",
+						snippet: { join: [
+							{
+								path: "author",
+								prefix: "UP: "
+							},
+							{
+								path: "play",
+								prefix: "播放: "
+							},
+							"duration"
+						] }
+					}
+				}
+			},
+			env: {},
+			needsLogin: false,
+			timeoutMs: 3e4,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "live",
+				version: BILI_CLI_VERSION,
+				date: SPEC_CHECK_DATE,
+				note: "`bili search DeepSeek --type video --max 2 --json` parsed (fixture bili-search.json)"
+			}
+		};
+		const ytDlp = {
+			id: "yt-dlp",
+			bins: ["yt-dlp"],
+			packageNote: "yt-dlp (uv tool install yt-dlp)",
+			platforms: ["youtube"],
+			probe: {
+				versionArgs: ["--version"],
+				helpArgs: ["--help"],
+				mustContain: [
+					"--flat-playlist",
+					"--print",
+					"--skip-download"
+				]
+			},
+			allowedSubcommands: [],
+			search: {
+				argv: [
+					"ytsearch{count}:{query}",
+					"--flat-playlist",
+					"--skip-download",
+					"--no-warnings",
+					"--print",
+					"%(id)s	%(title)s	%(channel)s	%(view_count)s	%(duration_string)s"
+				],
+				maxCount: 10,
+				output: {
+					format: "text",
+					lines: {
+						mode: "tsv",
+						columns: [
+							"id",
+							"title",
+							"channel",
+							"view_count",
+							"duration"
+						]
+					},
+					emptyValues: ["None"],
+					requireTitle: true,
+					fields: {
+						url: { template: "https://www.youtube.com/watch?v={id}" },
+						title: "title",
+						snippet: { join: [
+							"channel",
+							{
+								path: "view_count",
+								suffix: " views"
+							},
+							"duration"
+						] }
+					}
+				}
+			},
+			env: {},
+			needsLogin: false,
+			timeoutMs: 6e4,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "contract-only",
+				version: "2026.08.19",
+				date: SPEC_CHECK_DATE,
+				note: "help and version probed; flags from `yt-dlp --help`; the print template is the one the plugin has used since 0.1; no search was run"
+			}
+		};
+		const twitter = {
+			id: "twitter",
+			bins: ["twitter"],
+			packageNote: "twitter-cli (PyPI twitter-cli; the command is `twitter`; Agent-Reach alone does not provide it)",
+			platforms: ["twitter"],
+			probe: {
+				versionArgs: ["--version"],
+				helpArgs: ["search", "--help"],
+				mustContain: ["search"]
+			},
+			allowedSubcommands: ["search"],
+			search: {
+				argv: [
+					"search",
+					"{query}",
+					"-n",
+					"{count}"
+				],
+				maxCount: 10,
+				output: {
+					format: "text",
+					lines: { mode: "url-lines" },
+					titleMax: 200,
+					requireTitle: true,
+					fields: {
+						url: "url",
+						title: "title"
+					}
+				},
+				notLoggedInPatterns: [
+					"not authenticated",
+					"unauthorized",
+					"no twitter cookies",
+					"auth_token",
+					"ct0"
+				]
+			},
+			env: { required: ["TWITTER_AUTH_TOKEN", "TWITTER_CT0"] },
+			needsLogin: true,
+			timeoutMs: 45e3,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "contract-only",
+				version: "0.8.5",
+				date: SPEC_CHECK_DATE,
+				note: "help probed; the plain-text output (`search QUERY -n N`) is the one the plugin has used since 0.1; the tool also offers --json, not used here; no search was run (needs your tokens)"
+			}
+		};
+		const xhs = {
+			id: "xhs",
+			bins: ["xhs"],
+			packageNote: "xiaohongshu-cli (PyPI xiaohongshu-cli; the command is `xhs`)",
+			platforms: ["xiaohongshu"],
+			probe: {
+				versionArgs: ["--version"],
+				helpArgs: ["search", "--help"],
+				mustContain: [
+					"keyword",
+					"--json",
+					"--sort"
+				]
+			},
+			allowedSubcommands: ["search"],
+			search: {
+				argv: [
+					"search",
+					"{query}",
+					"--json"
+				],
+				output: {
+					format: "json",
+					itemsPath: "data.items",
+					expect: ENVELOPE,
+					errorPaths: ["error.message"],
+					fields: {
+						url: { template: "https://www.xiaohongshu.com/explore/{id}?xsec_token={xsec_token}&xsec_source=pc_search" },
+						title: ["note_card.display_title", "note_card.title"],
+						snippet: { join: [{
+							path: "note_card.user.nickname",
+							prefix: "作者: "
+						}, {
+							path: "note_card.interact_info.liked_count",
+							prefix: "赞: "
+						}] }
+					}
+				},
+				notLoggedInPatterns: NOT_LOGGED_IN
+			},
+			env: {},
+			needsLogin: true,
+			login: {
+				command: "xhs login",
+				savedCredentialPaths: ["~/.xiaohongshu-cli/cookies.json"],
+				readsBrowserCookiesWithoutLogin: true
+			},
+			timeoutMs: 45e3,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "contract-only",
+				version: "0.6.4",
+				date: SPEC_CHECK_DATE,
+				note: "help probed; output shape from the installed package source (client response + its own normalizer); no search was run: it needs your login and, without a saved one, reads browser cookies"
+			}
+		};
+		const zhihu = {
+			id: "zhihu",
+			bins: ["zhihu"],
+			packageNote: "zhihu-cli (PyPI pyzhihu-cli, BAIGUANGMEI/zhihu-cli; the command is `zhihu`; not the Access-Secret \"zhihu-cli\" of dawnswwwww)",
+			platforms: ["zhihu"],
+			probe: {
+				versionArgs: ["--version"],
+				helpArgs: ["search", "--help"],
+				mustContain: [
+					"query",
+					"--json",
+					"--limit",
+					"--type"
+				]
+			},
+			allowedSubcommands: ["search"],
+			search: {
+				argv: [
+					"search",
+					"{query}",
+					"--limit",
+					"{count}",
+					"--answers",
+					"0",
+					"--json"
+				],
+				maxCount: 20,
+				output: {
+					format: "json",
+					itemsPath: "data",
+					stripTags: true,
+					fields: {
+						url: [
+							{
+								template: "https://www.zhihu.com/question/{object.question.id}/answer/{object.id}",
+								when: {
+									path: "object.type",
+									equals: "answer"
+								}
+							},
+							{
+								template: "https://zhuanlan.zhihu.com/p/{object.id}",
+								when: {
+									path: "object.type",
+									equals: "article"
+								}
+							},
+							{
+								template: "https://www.zhihu.com/question/{object.id}",
+								when: {
+									path: "object.type",
+									equals: "question"
+								}
+							}
+						],
+						title: [
+							"object.title",
+							"object.question.name",
+							"object.name"
+						],
+						snippet: ["object.excerpt", "object.content"],
+						publishedAt: { epoch: "object.created_time" }
+					}
+				},
+				notLoggedInPatterns: ["not authenticated", "zhihu login"]
+			},
+			env: {},
+			needsLogin: true,
+			login: {
+				command: "zhihu login",
+				savedCredentialPaths: ["~/.zhihu-cli/cookies.json"]
+			},
+			timeoutMs: 45e3,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "contract-only",
+				version: "0.2.4",
+				date: SPEC_CHECK_DATE,
+				note: "help probed; output shape (`data[].object`) from the installed package source; the tool never reads browser cookies itself; no search was run (needs your login)"
+			}
+		};
+		const rdt = {
+			id: "rdt",
+			bins: ["rdt"],
+			packageNote: "rdt-cli (public-clis/rdt-cli; the command is `rdt`)",
+			platforms: ["reddit"],
+			probe: {
+				versionArgs: ["--version"],
+				helpArgs: ["search", "--help"],
+				mustContain: [
+					"query",
+					"--json",
+					"--compact",
+					"--limit"
+				]
+			},
+			allowedSubcommands: ["search"],
+			search: {
+				argv: [
+					"search",
+					"{query}",
+					"--limit",
+					"{count}",
+					"--compact",
+					"--json"
+				],
+				maxCount: 25,
+				output: {
+					format: "json",
+					itemsPath: "data",
+					expect: ENVELOPE,
+					errorPaths: ["error.message"],
+					fields: {
+						url: { template: "https://www.reddit.com{permalink}" },
+						title: "title",
+						snippet: { join: [
+							{
+								path: "subreddit",
+								prefix: "r/"
+							},
+							{
+								path: "score",
+								prefix: "score "
+							},
+							{
+								path: "num_comments",
+								suffix: " comments"
+							},
+							"selftext"
+						] },
+						publishedAt: { epoch: "created_utc" }
+					}
+				},
+				notLoggedInPatterns: NOT_LOGGED_IN
+			},
+			env: {},
+			needsLogin: true,
+			login: {
+				command: "rdt login",
+				savedCredentialPaths: ["~/.config/rdt-cli/credential.json"],
+				readsBrowserCookiesWithoutLogin: true
+			},
+			timeoutMs: 45e3,
+			maxOutputBytes: 4 * MB,
+			verification: {
+				status: "contract-only",
+				version: "0.4.2",
+				date: SPEC_CHECK_DATE,
+				note: "help probed; `--compact --json` output (post dicts in the `data` envelope) from the installed package source; no search was run: without a saved login it reads browser cookies"
+			}
+		};
+		const OMNIREACH_OUTPUT = {
+			format: "json",
+			itemsPath: "results",
+			errorPaths: ["errors.0.error"],
+			stripTags: true,
+			fields: {
+				url: "url",
+				title: "title",
+				snippet: "content",
+				publishedAt: "ts"
+			}
+		};
+		/** The `wechat` platform's two tools and the multi-source `omnireach` platform come from the same specs; ids are the backend ids. */
+		const BUILTIN_CLI_SPECS = [
+			bili,
+			ytDlp,
+			twitter,
+			xhs,
+			zhihu,
+			rdt,
+			{
+				id: "omnireach",
+				bins: ["omnireach"],
+				packageNote: "omnireach (Python, Daily-AC/omnireach; uv tool install from its repository)",
+				platforms: ["omnireach", "wechat"],
+				probe: {
+					versionArgs: ["--version"],
+					minVersion: "0.19.0",
+					helpArgs: ["search", "--help"],
+					mustContain: [
+						"--on",
+						"--limit",
+						"--json"
+					]
+				},
+				allowedSubcommands: ["search"],
+				search: {
+					argv: [
+						"search",
+						"{query}",
+						"--limit",
+						"{count}",
+						"--json"
+					],
+					maxCount: 20,
+					output: OMNIREACH_OUTPUT
+				},
+				searches: { wechat: {
+					argv: [
+						"search",
+						"{query}",
+						"--on",
+						"wechat",
+						"--limit",
+						"{count}",
+						"--json"
+					],
+					maxCount: 10,
+					output: OMNIREACH_OUTPUT
+				} },
+				env: {},
+				needsLogin: false,
+				timeoutMs: 6e4,
+				maxOutputBytes: 8 * MB,
+				verification: {
+					status: "live",
+					version: "0.19.0-alpha",
+					date: SPEC_CHECK_DATE,
+					note: "`omnireach search 大模型 备案 --on wechat --limit 2 --json` parsed (fixture omnireach-wechat.json); the multi-source command was not run"
+				}
+			},
+			{
+				id: "gh",
+				bins: ["gh"],
+				packageNote: "GitHub CLI (https://cli.github.com; brew install gh / winget install GitHub.cli)",
+				platforms: [
+					"github",
+					"github-issues",
+					"github-code"
+				],
+				probe: {
+					versionArgs: ["--version"],
+					helpArgs: [
+						"search",
+						"repos",
+						"--help"
+					],
+					mustContain: [
+						"--json",
+						"--limit",
+						"stargazersCount"
+					]
+				},
+				allowedSubcommands: [
+					"search",
+					"repos",
+					"issues",
+					"code"
+				],
+				search: {
+					argv: [
+						"search",
+						"repos",
+						"--json",
+						"fullName,description,url,stargazersCount,language,updatedAt,forksCount",
+						"--limit",
+						"{count}",
+						"--sort",
+						"stars",
+						"--order",
+						"desc",
+						"--",
+						"{query}"
+					],
+					maxCount: 15,
+					output: {
+						format: "json",
+						stripTags: false,
+						fields: {
+							url: "url",
+							title: "fullName",
+							publishedAt: { date: "updatedAt" },
+							snippet: { join: [
+								"description",
+								{
+									path: "stargazersCount",
+									prefix: "⭐"
+								},
+								{
+									path: "language",
+									prefix: "[",
+									suffix: "]"
+								},
+								{
+									path: "forksCount",
+									prefix: "forks "
+								}
+							] }
+						}
+					},
+					notLoggedInPatterns: [
+						"gh auth login",
+						"not logged in",
+						"authentication required"
+					]
+				},
+				searches: {
+					"github-issues": {
+						argv: [
+							"search",
+							"issues",
+							"--json",
+							"title,url,state,repository,commentsCount,updatedAt",
+							"--limit",
+							"{count}",
+							"--sort",
+							"updated",
+							"--order",
+							"desc",
+							"--",
+							"{query}"
+						],
+						maxCount: 15,
+						output: {
+							format: "json",
+							fields: {
+								url: "url",
+								title: "title",
+								publishedAt: { date: "updatedAt" },
+								snippet: {
+									join: [
+										{
+											path: "state",
+											prefix: "[",
+											suffix: "]"
+										},
+										"repository.nameWithOwner",
+										{
+											path: "commentsCount",
+											suffix: " comments"
+										}
+									],
+									sep: " · "
+								}
+							}
+						},
+						notLoggedInPatterns: [
+							"gh auth login",
+							"not logged in",
+							"authentication required"
+						]
+					},
+					"github-code": {
+						argv: [
+							"search",
+							"code",
+							"--json",
+							"path,repository,url",
+							"--limit",
+							"{count}",
+							"--",
+							"{query}"
+						],
+						maxCount: 15,
+						output: {
+							format: "json",
+							fields: {
+								url: "url",
+								title: { template: "{repository.nameWithOwner} / {path}" },
+								snippet: { template: "仓库: {repository.nameWithOwner}" }
+							}
+						},
+						notLoggedInPatterns: [
+							"gh auth login",
+							"not logged in",
+							"authentication required"
+						]
+					}
+				},
+				env: { passthrough: [
+					"GH_TOKEN",
+					"GITHUB_TOKEN",
+					"GH_HOST",
+					"GH_CONFIG_DIR"
+				] },
+				needsLogin: true,
+				login: { command: "gh auth login" },
+				timeoutMs: 3e4,
+				maxOutputBytes: 4 * MB,
+				verification: {
+					status: "live",
+					version: "2.101.0",
+					date: SPEC_CHECK_DATE,
+					note: "`gh search repos --json … --sort stars -- \"dsh web search\"` parsed (fixture gh-repos.json); issues and code searches follow the documented JSON fields of their help pages and were not run"
+				}
+			},
+			{
+				id: "wx-search-cli",
+				bins: ["wx-search-cli"],
+				packageNote: "wx-search-cli (npm i -g wx-search-cli, tjx666/wx-search-cli; the command is `wx-search-cli`)",
+				platforms: ["wechat"],
+				probe: {
+					versionArgs: ["--version"],
+					helpArgs: ["--help"],
+					mustContain: ["search <query>", "sogou"]
+				},
+				allowedSubcommands: ["search"],
+				search: {
+					argv: ["search", "{query}"],
+					output: {
+						format: "json",
+						fields: {
+							url: "real_url",
+							title: "title",
+							publishedAt: "publish_time"
+						}
+					}
+				},
+				env: {},
+				needsLogin: false,
+				timeoutMs: 45e3,
+				maxOutputBytes: 2 * MB,
+				verification: {
+					status: "contract-only",
+					version: "0.1.0",
+					date: SPEC_CHECK_DATE,
+					note: "help and version probed on a real install; output shape (JSON array of { title, link, real_url, publish_time, page }) from the upstream README and src/index.ts read with gh api; no search was run"
+				}
+			},
+			{
+				id: "tanso",
+				bins: ["tanso"],
+				packageNote: "tanso (npm i -g @geekjourneyx/tanso, geekjourneyx/tanso; a Go binary; needs your Bocha / Zhihu keys in its own config)",
+				platforms: ["tanso"],
+				probe: {
+					versionArgs: ["version"],
+					helpArgs: ["--help"],
+					mustContain: [
+						"bocha",
+						"zhihu",
+						"--json"
+					]
+				},
+				allowedSubcommands: ["version"],
+				search: {
+					argv: [
+						"{query}",
+						"--json",
+						"--source",
+						"bocha_web",
+						"--source",
+						"zhihu_search"
+					],
+					output: {
+						format: "json",
+						itemsPath: "results",
+						errorPaths: ["errors.0.message", "errors.0"],
+						fields: {
+							url: "url",
+							title: "title",
+							snippet: "snippet"
+						}
+					},
+					notLoggedInPatterns: [
+						"credential",
+						"api_key",
+						"access_secret",
+						"config error"
+					]
+				},
+				env: { passthrough: [
+					"BOCHA_API_KEY",
+					"ZHIHU_ACCESS_SECRET",
+					"ZHIHU_API_KEY",
+					"TANSO_CONFIG",
+					"XDG_CONFIG_HOME"
+				] },
+				needsLogin: true,
+				login: { command: "tanso config init" },
+				timeoutMs: 6e4,
+				maxOutputBytes: 2 * MB,
+				verification: {
+					status: "docs-only",
+					version: "2.0.2",
+					date: SPEC_CHECK_DATE,
+					note: "not installed here; from the upstream README (envelope with results[].{source,title,url,snippet}); --limit is not documented and not used"
+				}
+			}
+		];
+		for (const spec of BUILTIN_CLI_SPECS) {
+			const result = validateCliAdapterSpec(spec, "builtin");
+			if (!result.ok) throw new Error("built-in CLI spec " + spec.id + " is invalid: " + result.errors.join("; "));
+		}
+		/** Platforms whose provider is a chain (everything in the default table). */
+		const CHAIN_PLATFORMS = Object.keys({
+			xiaohongshu: [
+				"opencli",
+				"xhs",
+				"browser-opencli"
+			],
+			reddit: [
+				"rdt",
+				"opencli",
+				"browser-opencli"
+			],
+			twitter: [
+				"twitter",
+				"opencli",
+				"browser-opencli"
+			],
+			zhihu: ["zhihu", "browser-search"],
+			bilibili: ["bili"],
+			youtube: ["yt-dlp"],
+			github: ["rest", "gh"],
+			"github-issues": ["rest", "gh"],
+			"github-code": ["rest", "gh"],
+			wechat: ["omnireach", "wx-search-cli"],
+			omnireach: ["omnireach"],
+			tanso: ["tanso"],
+			instagram: ["browser-opencli"],
+			facebook: ["browser-opencli"],
+			weibo: ["browser-search"],
+			douban: ["browser-search"],
+			tieba: ["browser-search"],
+			douyin: ["browser-search"],
+			kuaishou: ["browser-search"]
+		});
+		/** Platform -> site of the standalone OpenCLI (`opencli <site> search`). */
+		const OPENCLI_SITE_OF = {
+			xiaohongshu: "xiaohongshu",
+			twitter: "twitter",
+			reddit: "reddit",
+			instagram: "instagram",
+			facebook: "facebook",
+			zhihu: "zhihu",
+			weibo: "weibo",
+			douban: "douban",
+			tieba: "tieba",
+			douyin: "douyin",
+			bilibili: "bilibili",
+			youtube: "youtube",
+			wechat: "weixin"
+		};
+		/** Platforms the dsh-browser OpenCLI bridge has a site adapter for (pinned to engines.ts by a test). */
+		const BROWSER_OPENCLI_PLATFORMS = [
+			"xiaohongshu",
+			"twitter",
+			"reddit",
+			"instagram",
+			"facebook"
+		];
+		/** Platforms with a built-in rendered-search-page spec in dsh-browser's searchResults (pinned to platform-search.ts by a test). */
+		const BROWSER_SEARCH_PLATFORMS = [
+			"zhihu",
+			"weibo",
+			"douban",
+			"tieba",
+			"douyin",
+			"kuaishou"
+		];
+		/** Platforms the plugin's own REST client serves. */
+		const REST_PLATFORMS = [
+			"github",
+			"github-issues",
+			"github-code"
+		];
+		/** Backend ids that are not CLI specs. */
+		const FIXED_BACKENDS = [
+			"opencli",
+			"browser-opencli",
+			"browser-search",
+			"rest"
+		];
+		/**
+		* Whether backend `id` can serve `platform`. `specPlatforms` maps a CLI spec id (built-in, or `custom-cli:<id>` of the user)
+		* to the platforms it lists; a user spec serves any platform its chain names.
+		*/
+		function backendServes(id, platform, specPlatforms) {
+			if (id === "opencli") return OPENCLI_SITE_OF[platform] ? { ok: true } : {
+				ok: false,
+				why: "has no site for platform " + platform
+			};
+			if (id === "browser-opencli") return BROWSER_OPENCLI_PLATFORMS.includes(platform) ? { ok: true } : {
+				ok: false,
+				why: "does not serve platform " + platform
+			};
+			if (id === "browser-search") return BROWSER_SEARCH_PLATFORMS.includes(platform) ? { ok: true } : {
+				ok: false,
+				why: "does not serve platform " + platform
+			};
+			if (id === "rest") return REST_PLATFORMS.includes(platform) ? { ok: true } : {
+				ok: false,
+				why: "does not serve platform " + platform
+			};
+			const platforms = specPlatforms.get(id);
+			if (!platforms) return {
+				ok: false,
+				why: "is not a known backend (built-in ids: " + [...specPlatforms.keys()].filter((k) => !k.startsWith("custom-cli:")).join(", ") + ", " + FIXED_BACKENDS.join(", ") + ")"
+			};
+			if (!id.startsWith("custom-cli:") && !platforms.includes(platform)) return {
+				ok: false,
+				why: "does not serve platform " + platform + " (it serves " + platforms.join(", ") + ")"
+			};
+			return { ok: true };
+		}
+		/** The CLI specs a chain may name: the built-ins by id and the user's valid `cliAdapters` as `custom-cli:<id>`. */
+		function specPlatformsOf(cliAdapters) {
+			const platforms = new Map(BUILTIN_CLI_SPECS.map((spec) => [spec.id, spec.platforms]));
+			const user = resolveCliAdapters(cliAdapters);
+			for (const [id, spec] of user.specs) platforms.set("custom-cli:" + id, spec.platforms);
+			return {
+				platforms,
+				diagnostics: user.diagnostics
+			};
+		}
+		/**
+		* Every problem of the `platformBackends` setting (shape, unknown platform, unknown or foreign backend id) given the
+		* `cliAdapters` setting. The settings card and `sources.status` both call this.
+		*/
+		function platformBackendIssues(platformBackends, cliAdapters) {
+			const shape = platformBackendProblems(platformBackends);
+			if (shape.length || !platformBackends || typeof platformBackends !== "object") return shape;
+			const { platforms } = specPlatformsOf(cliAdapters);
+			const known = /* @__PURE__ */ new Set([...CHAIN_PLATFORMS, ...[...platforms.keys()].filter((id) => id.startsWith("custom-cli:"))]);
+			const out = [];
+			for (const [platform, ids] of Object.entries(platformBackends)) {
+				if (!known.has(platform)) {
+					out.push("platformBackends." + platform + ": no such platform with a backend chain (known: " + [...known].join(", ") + ")");
+					continue;
+				}
+				for (const id of ids) {
+					const served = backendServes(id, platform, platforms);
+					if (!served.ok) out.push("platformBackends." + platform + ": \"" + id + "\" " + served.why);
+				}
+			}
+			return out;
+		}
+		//#endregion
 		//#region src/client/validators.ts
 		/**
 		* Validation behind the settings card. Every rule that has a server counterpart is the server's own function
@@ -1179,6 +2559,26 @@ window.__ModuleLoader__.load({
 		function unknownRubricIds(rubrics) {
 			return isRecord(rubrics) ? Object.keys(rubrics).filter((id) => !BUILTIN_RUBRIC_IDS.includes(id)) : [];
 		}
+		/**
+		* Problems of the CLI adapter settings, from the server's own functions: `cliAdapters` entries the server would ignore
+		* (read-only guard, bad argv, secrets in env) and `platformBackends` that name an unknown platform or a backend that
+		* cannot serve it.
+		*/
+		function cliIssues(platformBackends, cliAdapters) {
+			const issues = [];
+			for (const message of resolveCliAdapters(cliAdapters).diagnostics) issues.push({
+				field: "cliAdapters",
+				message,
+				level: "error"
+			});
+			for (const message of platformBackendIssues(platformBackends, cliAdapters)) issues.push({
+				field: "platformBackends",
+				message,
+				level: "error",
+				related: ["cliAdapters"]
+			});
+			return issues;
+		}
 		//#endregion
 		//#region src/client/form.ts
 		const ROOTS = [
@@ -1592,9 +2992,21 @@ window.__ModuleLoader__.load({
 				const base = this.scope.getSnapshot().base?.evidence;
 				const evidence = deepMerge(isRecord(base) ? base : {}, candidates.get("evidence"));
 				const baseSources = this.scope.getSnapshot().base?.sources;
-				const issues = [...evidenceIssues(evidence), ...sourcesIssues(deepMerge(isRecord(baseSources) ? baseSources : {}, candidates.get("sources")))];
+				const topValue = (field) => {
+					const draft = this.staged.get(field);
+					if (draft === void 0) return this.sectionValue(field);
+					if (draft.clear) return void 0;
+					const write = this.spec(field).parse(draft.text);
+					return write?.kind === "set" ? write.value : void 0;
+				};
+				const issues = [
+					...evidenceIssues(evidence),
+					...sourcesIssues(deepMerge(isRecord(baseSources) ? baseSources : {}, candidates.get("sources"))),
+					...cliIssues(topValue("platformBackends"), topValue("cliAdapters"))
+				];
 				const blocked = /* @__PURE__ */ new Set();
-				for (const issue of issues) if (issue.level === "error" && (staged.has(issue.field) || (issue.related ?? []).some((related) => staged.has(related)))) blocked.add(issue.field);
+				const touched = (field) => staged.has(field) || this.staged.has(field);
+				for (const issue of issues) if (issue.level === "error" && (touched(issue.field) || (issue.related ?? []).some((related) => touched(related)))) blocked.add(issue.field);
 				return {
 					settings,
 					issues,
@@ -2724,7 +4136,9 @@ window.__ModuleLoader__.load({
 									toggle("enableCliBackends", "enableCliBackends", "enableCliBackendsHint"),
 									toggle("opencliEnabled", "opencliEnabled", "opencliEnabledHint"),
 									toggle("agentReachEnabled", "agentReachEnabled", "agentReachEnabledHint"),
-									json("playwright", "playwright", "playwrightHint", 4)
+									json("playwright", "playwright", "playwrightHint", 4),
+									json("platformBackends", "platformBackends", "platformBackendsHint", 7),
+									json("cliAdapters", "cliAdapters", "cliAdaptersHint", 12)
 								]
 							})
 						}),
@@ -2859,6 +4273,10 @@ window.__ModuleLoader__.load({
 			platformRulesHint: "按平台设置 item/title/link/text 选择器。",
 			customPlatforms: "自定义平台（JSON）",
 			customPlatformsHint: "按平台定义搜索 URL 与选择器；登录态请通过浏览器绑定引用 AuthProfile。",
+			platformBackends: "平台后端顺序（JSON）",
+			platformBackendsHint: "每个平台依次尝试的后端，如 {\"xiaohongshu\": [\"xhs\", \"opencli\", \"browser-opencli\"]}。id：各 CLI（xhs、rdt、zhihu、twitter、bili、yt-dlp、omnireach、wx-search-cli、gh、tanso）、opencli、browser-opencli、browser-search、rest、custom-cli:<id>。缺失或未登录的后端会被跳过并说明原因。",
+			cliAdapters: "自定义 CLI 适配（JSON）",
+			cliAdaptersHint: "按 id 定义只读 CLI 适配规格（argv 数组、输出字段、探测契约、allowedSubcommands）。写操作和读取浏览器 Cookie 的参数会被拒绝；无效条目被忽略并在 sources.status 说明。登录始终由你自己运行 CLI。",
 			browserBindings: "浏览器绑定（JSON）",
 			browserBindingsHint: "把平台绑定到 dsh-browser AuthProfile 与 RulePack。",
 			verbose: "详细诊断日志",
@@ -3087,6 +4505,10 @@ window.__ModuleLoader__.load({
 			platformRulesHint: "Set item/title/link/text selectors per platform.",
 			customPlatforms: "Custom platforms (JSON)",
 			customPlatformsHint: "Define search URLs and selectors; bind an AuthProfile for authenticated access.",
+			platformBackends: "Platform backend order (JSON)",
+			platformBackendsHint: "Backends each platform tries in order, e.g. {\"xiaohongshu\": [\"xhs\", \"opencli\", \"browser-opencli\"]}. Ids: the CLIs (xhs, rdt, zhihu, twitter, bili, yt-dlp, omnireach, wx-search-cli, gh, tanso), opencli, browser-opencli, browser-search, rest, custom-cli:<id>. A missing or logged-out backend is skipped with its reason.",
+			cliAdapters: "Custom CLI adapters (JSON)",
+			cliAdaptersHint: "Read-only CLI adapter specs by id (argv array, output fields, probe contract, allowedSubcommands). Write commands and cookie-reading flags are rejected; an invalid entry is ignored and explained in sources.status. Logging in is always yours to do.",
 			browserBindings: "Browser bindings (JSON)",
 			browserBindingsHint: "Bind platforms to dsh-browser AuthProfiles and RulePacks.",
 			verbose: "Verbose diagnostics",