@oh-agent/dsh-mcp-manager 0.0.0-stage → 0.1.0

package/lib/dsh-patch.js

@@ -0,0 +1,329 @@
+/**
+ * Adding MCP rows to DeepSeek Harness, not just editing existing ones.
+ *
+ * `configEditor.edit()` can only rewrite a row that already exists; a brand-new
+ * MCP server has no entry to address. The composition's patch layer is the
+ * supported insertion point (`- insert:` is a documented top-level patch
+ * entry), so new servers are appended there and existing ones are rewritten
+ * through configEditor.
+ *
+ * These helpers only touch `- insert:` items that this plugin created (matched
+ * by the `mcp-<serverName>` id plus the mcp-client package name), so a user's
+ * own patch entries — provider configs, agency agents, anything hand-written —
+ * are never rewritten. Every write is backed up by the store first.
+ */
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { MCP_CLIENT_PACKAGE, encodeDshEntry } from './dsh.js';
+
+const INSERT_ID_PREFIX = 'mcp-';
+
+/** Where the active profile keeps its patch layer. */
+export function profilePatchPath(profileDir) {
+  const base = profileDir ?? process.env.DSH_PROFILE_DIR ?? (process.env.DSH_HOME ? join(process.env.DSH_HOME, 'profiles', 'desktop') : undefined);
+  if (!base) return undefined;
+  return join(base, 'cordis.patch.yml');
+}
+
+/**
+ * Split a patch file into its preamble (comments before the first entry) and
+ * its top-level `- ` items, keeping each item's source text verbatim.
+ *
+ * A byte-preserving split is what makes targeted removal safe: rebuilding the
+ * file from items we did not author would reformat the user's own entries.
+ */
+export function splitPatchItems(text) {
+  const lines = text.split('\n');
+  const preamble = [];
+  const items = [];
+  let current = null;
+  for (const line of lines) {
+    if (/^- /.test(line)) {
+      if (current) items.push(current);
+      current = [];
+    }
+    if (current) current.push(line);
+    else preamble.push(line);
+  }
+  if (current) items.push(current);
+  return {
+    preamble: preamble.join('\n'),
+    items: items.map((itemLines) => ({ lines: itemLines, text: itemLines.join('\n') })),
+  };
+}
+
+/** True when this patch item is an mcp-client row this plugin owns. */
+function isOurMcpItem(itemText, serverName) {
+  if (!/^- insert:/.test(itemText)) return false;
+  if (!itemText.includes(MCP_CLIENT_PACKAGE)) return false;
+  const wanted = `${INSERT_ID_PREFIX}${serverName}`;
+  return new RegExp(`^\\s*-\\s+id:\\s*["']?${escapeRegExp(wanted)}["']?\\s*$`, 'm').test(itemText);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * True when this patch item is the enablement override the plugin manager
+ * appends for one of our rows.
+ *
+ * `pluginManager.setPluginEnabled` does not rewrite the row: it appends a
+ * separate top-level item that targets the row by id with nothing but
+ * `disabled:`. That item is a second thing on disk describing the same server,
+ * so removal has to take it too — a targeted patch entry pointing at an id no
+ * longer in the tree is a dangling override.
+ */
+function isToggleOverrideItem(itemText, serverName) {
+  if (/^- insert:/.test(itemText)) return false;
+  if (!/^\s*disabled:\s*(true|false|null)\s*$/m.test(itemText)) return false;
+  const wanted = `${INSERT_ID_PREFIX}${serverName}`;
+  return new RegExp(`^-\\s+id:\\s*["']?${escapeRegExp(wanted)}["']?\\s*$`, 'm').test(itemText);
+}
+
+/** Is one of our servers currently disabled by a plugin-manager override? */
+function isDisabledByOverride(itemText, serverName) {
+  if (!isToggleOverrideItem(itemText, serverName)) return false;
+  return /^\s*disabled:\s*true\s*$/m.test(itemText);
+}
+
+/**
+ * Switch one of our patch-layer servers on or off before its row has mounted.
+ *
+ * This writes the same shape `pluginManager.setPluginEnabled` writes: a
+ * top-level item targeting the row by id with nothing but `disabled:`. It is
+ * deliberately not a rewrite of the insert item, so the server definition the
+ * user pasted stays byte-identical and re-enabling restores the file exactly.
+ */
+export function setDshPatchDisabled({ serverName, disabled, store, profileDir }) {
+  const path = profilePatchPath(profileDir);
+  if (!path || !existsSync(path)) return { ok: false, code: 'error.dsh.missing', error: 'no profile patch file' };
+  const before = readFileSync(path, 'utf8');
+  const { preamble, items } = splitPatchItems(before);
+  const hasRow = items.some((item) => isOurMcpItem(item.text, serverName));
+  if (!hasRow) return { ok: false, code: 'error.dsh.missing', error: `no patch row for ${serverName}` };
+  const others = items.filter((item) => !isToggleOverrideItem(item.text, serverName));
+  const id = `${INSERT_ID_PREFIX}${serverName}`;
+  const next = disabled ? [...others.map((item) => item.text.trimEnd()), `- id: ${id}\n  disabled: true`] : others.map((item) => item.text.trimEnd());
+  const head = preamble.trimEnd();
+  const after = (head ? [head, ...next] : next).join('\n');
+  const text = after ? `${after}\n` : '';
+  if (text === before) return { ok: true, changed: false, path, serverName };
+  if (store && typeof store.backup === 'function') {
+    try {
+      store.backup(path, before);
+    } catch { /* the item is a reversible one-liner; a missing backup cannot lose data */ }
+  }
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, text, 'utf8');
+  renameSync(tmp, path);
+  return { ok: true, changed: true, path, serverName, restartRequired: true };
+}
+
+/** Render one `- insert:` patch item for a server. */
+export function renderInsertItem(server) {
+  const config = encodeDshEntry(server);
+  const lines = [
+    '- insert:',
+    `    - id: ${INSERT_ID_PREFIX}${config.serverName}`,
+    `      name: '${MCP_CLIENT_PACKAGE}'`,
+    '      config:',
+  ];
+  const walk = (object, depth) => {
+    for (const [key, value] of Object.entries(object)) {
+      const pad = ' '.repeat(depth);
+      if (Array.isArray(value)) {
+        lines.push(`${pad}${key}:`);
+        for (const entry of value) lines.push(`${pad}  - ${JSON.stringify(entry)}`);
+      } else if (value && typeof value === 'object') {
+        lines.push(`${pad}${key}:`);
+        walk(value, depth + 2);
+      } else {
+        lines.push(`${pad}${key}: ${typeof value === 'string' ? JSON.stringify(value) : value}`);
+      }
+    }
+  };
+  walk(config, 8);
+  return { text: lines.join('\n'), serverName: config.serverName };
+}
+
+/**
+ * Add one server to the patch layer, or replace the item this plugin wrote
+ * earlier for the same serverName.
+ *
+ * Returns `{ ok, changed, path, serverName }`; `changed:false` means the exact
+ * item was already present, so a repeated apply is a no-op rather than a
+ * duplicate row.
+ */
+export function writeDshPatchServer({ server, store, profileDir }) {
+  const path = profilePatchPath(profileDir);
+  if (!path) return { ok: false, code: 'error.dsh.noProfile', error: 'cannot locate the active DSH profile' };
+  const existed = existsSync(path);
+  const before = existed ? readFileSync(path, 'utf8') : '';
+  const { text: itemText, serverName } = renderInsertItem(server);
+
+  const { preamble, items } = splitPatchItems(before);
+  const kept = [];
+  let replaced = false;
+  for (const item of items) {
+    if (isOurMcpItem(item.text, serverName)) {
+      if (item.text.trim() === itemText.trim()) replaced = true;
+      continue; // drop; the fresh item is appended below
+    }
+    kept.push(item.text);
+  }
+  if (replaced) return { ok: true, changed: false, path, serverName };
+
+  const head = preamble.trimEnd();
+  const chunks = [];
+  if (head) chunks.push(head);
+  for (const item of kept) chunks.push(item.trimEnd());
+  chunks.push(itemText);
+  const after = `${chunks.join('\n')}\n`;
+
+  if (store && typeof store.backup === 'function') {
+    try {
+      store.backup(path, before);
+    } catch { /* a missing backup must not block the write; the item is additive */ }
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}`;
+  writeFileSync(temp, after, 'utf8');
+  renameSync(temp, path);
+  return { ok: true, changed: true, path, serverName, created: !existed };
+}
+
+/** Remove the patch item this plugin wrote for one serverName. */
+export function removeDshPatchServer({ serverName, store, profileDir }) {
+  const path = profilePatchPath(profileDir);
+  if (!path || !existsSync(path)) return { ok: true, changed: false, path };
+  const before = readFileSync(path, 'utf8');
+  const { preamble, items } = splitPatchItems(before);
+  // Take the enablement override with the row, or the override outlives its target.
+  const kept = items.filter((item) => !isOurMcpItem(item.text, serverName) && !isToggleOverrideItem(item.text, serverName));
+  if (kept.length === items.length) return { ok: true, changed: false, path };
+
+  if (store && typeof store.backup === 'function') {
+    try {
+      store.backup(path, before);
+    } catch { /* keep going: the write itself is still safe */ }
+  }
+  const head = preamble.trimEnd();
+  const chunks = head ? [head, ...kept.map((item) => item.text.trimEnd())] : kept.map((item) => item.text.trimEnd());
+  const after = chunks.length ? `${chunks.join('\n')}\n` : '';
+  const temp = `${path}.tmp-${process.pid}`;
+  writeFileSync(temp, after, 'utf8');
+  renameSync(temp, path);
+  return { ok: true, changed: true, path };
+}
+
+/** Does the patch layer already carry an item for this serverName? */
+export function patchHasServer(serverName, profileDir) {
+  const path = profilePatchPath(profileDir);
+  if (!path || !existsSync(path)) return false;
+  const { items } = splitPatchItems(readFileSync(path, 'utf8'));
+  return items.some((item) => isOurMcpItem(item.text, serverName));
+}
+
+/**
+ * Read the MCP servers this plugin put in the patch layer.
+ *
+ * These are *pending*: the row exists on disk but only becomes a live entry
+ * after the Loader reconciles (a restart). `scanAll` merges them with the live
+ * rows, live first, so a server is never counted twice once it has taken
+ * effect, and the UI can still show one that was just written.
+ */
+export function readDshPatchServers(profileDir) {
+  const path = profilePatchPath(profileDir);
+  if (!path || !existsSync(path)) return [];
+  const out = [];
+  const { items } = splitPatchItems(readFileSync(path, 'utf8'));
+  for (const item of items) {
+    if (!/^- insert:/.test(item.text) || !item.text.includes(MCP_CLIENT_PACKAGE)) continue;
+    const idMatch = item.text.match(/^\s*-\s+id:\s*["']?([^"'\s]+)["']?\s*$/m);
+    if (!idMatch || !idMatch[1].startsWith(INSERT_ID_PREFIX)) continue;
+    const server = parseInsertItem(item.text);
+    if (!server) continue;
+    // A plugin-manager override can switch this row off without touching it.
+    const disabled = items.some((other) => isDisabledByOverride(other.text, server.name));
+    out.push({ ...server, enabled: !disabled, pending: true, patchPath: path, patchId: idMatch[1] });
+  }
+  return out;
+}
+
+/**
+ * Pull the `config:` block out of one insert item.
+ *
+ * The block this plugin writes is deliberately shallow (scalars, string lists,
+ * and one level of string maps for env/headers), so a small purpose-built
+ * reader is enough and avoids adding a YAML dependency to the bundle.
+ */
+function parseInsertItem(itemText) {
+  const lines = itemText.split('\n');
+  const start = lines.findIndex((line) => /^\s+config:\s*$/.test(line));
+  if (start < 0) return null;
+  const configIndent = lines[start].match(/^\s*/)[0].length;
+  const config = {};
+  let currentKey = null;
+  let currentIndent = -1;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim()) continue;
+    const indent = line.match(/^\s*/)[0].length;
+    if (indent <= configIndent) break;
+    const listItem = line.match(/^\s*-\s+(.*)$/);
+    if (listItem) {
+      if (currentKey) {
+        /* A key with no inline value is a map or a list; the first item decides. */
+        if (!Array.isArray(config[currentKey])) config[currentKey] = [];
+        config[currentKey].push(unquote(listItem[1]));
+      }
+      continue;
+    }
+    const pair = line.match(/^\s*([A-Za-z0-9_.-]+):\s*(.*)$/);
+    if (!pair) continue;
+    const [, key, rest] = pair;
+    if (rest === '') {
+      currentKey = key;
+      currentIndent = indent;
+      config[key] = config[key] ?? {};
+      continue;
+    }
+    if (currentKey && indent > currentIndent && typeof config[currentKey] === 'object' && !Array.isArray(config[currentKey])) {
+      config[currentKey][key] = unquote(rest);
+      continue;
+    }
+    currentKey = null;
+    config[key] = rest === '[]' ? [] : unquote(rest);
+  }
+  if (!config.serverName) return null;
+  return {
+    name: config.serverName,
+    transport: config.transport === 'streamable-http' ? 'http-stream' : 'stdio',
+    command: config.command,
+    args: Array.isArray(config.args) ? config.args : config.args ? [config.args] : [],
+    env: typeof config.env === 'object' && !Array.isArray(config.env) ? config.env : {},
+    headers: typeof config.headers === 'object' && !Array.isArray(config.headers) ? config.headers : {},
+    url: config.url,
+    timeoutMs: typeof config.toolCallTimeoutMs === 'number' ? config.toolCallTimeoutMs : undefined,
+    enabled: true,
+    pending: true,
+  };
+}
+
+function unquote(value) {
+  const text = String(value).trim();
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (/^'.*'$/.test(text)) return text.slice(1, -1).replace(/''/g, "'");
+  if (/^".*"$/.test(text)) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}

package/lib/dsh.js

@@ -0,0 +1,259 @@
+/**
+ * DeepSeek Harness as one more MCP target.
+ *
+ * DSH stores MCP servers as `@deepseek-ai/dsh-mcp-client` rows in a cordis
+ * composition, not as JSON. Writing those files by hand would mean guessing at
+ * YAML form (including `!!js` expressions) and requiring a restart to see any
+ * effect. `configEditor.edit()` does it properly: it validates the config
+ * against the plugin's schema, persists it, and reconciles the Loader, and
+ * mcp-client applies changes hot.
+ *
+ * Two constraints come from mcp-client's own schema and are enforced here
+ * rather than discovered as a startup failure:
+ *   - `serverName` must match `[A-Za-z0-9_-]{1,32}` and be unique per scope
+ *   - `transport` is `stdio` or `streamable-http`; there is no `sse` and no
+ *     separate timeout field beyond `toolCallTimeoutMs`
+ */
+
+import { dshMountName, sanitizeName } from './canonical.js';
+
+export const MCP_CLIENT_PACKAGE = '@deepseek-ai/dsh-mcp-client';
+const SERVER_NAME_RE = /^[A-Za-z0-9_-]{1,32}$/;
+
+/**
+ * The plugin package a Loader entry instantiates.
+ *
+ * Read `options.name`, not `name`: the live Loader entry carries no `name`
+ * property at all (verified on a running Host — `entry.name` is `undefined`
+ * while `entry.options.name` is `'@deepseek-ai/dsh-mcp-client'`). Checking
+ * `entry.name` silently matched zero rows, which made the scanner believe every
+ * DSH server was still unreconciled in the patch layer and report it as
+ * needing a restart. Accept both shapes so a future Loader that sets `name`
+ * keeps working.
+ */
+function entryPackageName(entry) {
+  if (!entry) return '';
+  if (typeof entry.name === 'string') return entry.name;
+  const options = entry.options;
+  return options && typeof options.name === 'string' ? options.name : '';
+}
+
+/** Every composition row that is an MCP client. */
+export function mcpEntries(configEditor) {
+  if (!configEditor || typeof configEditor.configuration !== 'function') return [];
+  try {
+    return configEditor.configuration().filter((row) => {
+      const name = entryPackageName(row && row.entry);
+      return name === MCP_CLIENT_PACKAGE || name.endsWith('/dsh-mcp-client');
+    });
+  } catch {
+    return [];
+  }
+}
+
+/** Decode our canonical model from one mcp-client row config. */
+export function decodeDshEntry(entry, config) {
+  const raw = config && typeof config === 'object' ? config : {};
+  const transport = raw.transport === 'streamable-http' ? 'http-stream' : 'stdio';
+  const env = raw.env && typeof raw.env === 'object' ? { ...raw.env } : {};
+  const headers = raw.headers && typeof raw.headers === 'object' ? { ...raw.headers } : {};
+  return {
+    name: raw.serverName ?? entry?.id ?? 'unknown',
+    entryId: entry?.id,
+    transport,
+    command: raw.command ?? '',
+    args: Array.isArray(raw.args) ? raw.args.map(String) : [],
+    env,
+    cwd: raw.cwd,
+    url: raw.url,
+    headers,
+    timeoutMs: typeof raw.toolCallTimeoutMs === 'number' ? raw.toolCallTimeoutMs : 60000,
+    enabled: !(entry && entry.disabled === true),
+    autoApprove: [],
+    extra: {
+      failOnStartupError: raw.failOnStartupError,
+      reconnect: raw.reconnect,
+    },
+    secrets: [
+      ...Object.entries(env).map(([key, value]) => ({ where: 'env', key, value })),
+      ...Object.entries(headers).map(([key, value]) => ({ where: 'headers', key, value })),
+    ]
+      .filter((item) => /token|key|secret|password|auth|cookie/i.test(item.key) && typeof item.value === 'string' && item.value.length >= 12)
+      .map(({ where, key }) => ({ where, key })),
+    raw,
+  };
+}
+
+/**
+ * Encode the canonical model into an mcp-client config object.
+ *
+ * mcp-client has exactly two transports. A canonical `http-sse` has to become
+ * `streamable-http`: collapsing it to `stdio` would emit a config with no
+ * command (a row that never starts), which is worse than a transport hint the
+ * connection may negotiate away.
+ */
+export function encodeDshEntry(server) {
+  const remote = server.transport === 'http-stream' || server.transport === 'http-sse';
+  /*
+   * A caller may pass an already-mapped mount name (the scan reports it as
+   * `mountName`); otherwise derive the same mapping from the display name so a
+   * write and a later lookup always agree.
+   */
+  const mountName = server.mountName ? sanitizeName(server.mountName) : dshMountName(server.serverName ?? server.name);
+  const config = { serverName: mountName, transport: remote ? 'streamable-http' : 'stdio' };
+  if (!remote) {
+    config.command = server.command;
+    if (server.args && server.args.length) config.args = [...server.args];
+    if (server.env && Object.keys(server.env).length) config.env = { ...server.env };
+    if (server.cwd) config.cwd = server.cwd;
+  } else {
+    config.url = server.url;
+    if (server.headers && Object.keys(server.headers).length) config.headers = { ...server.headers };
+  }
+  if (typeof server.timeoutMs === 'number' && server.timeoutMs > 0) config.toolCallTimeoutMs = server.timeoutMs;
+  for (const key of ['failOnStartupError', 'reconnect']) {
+    const value = server.extra?.[key];
+    if (value !== undefined) config[key] = value;
+  }
+  return config;
+}
+
+/**
+ * Add or replace one MCP server row. `previous` is the row to replace; when
+ * absent a fresh row id is derived from the server name.
+ */
+export async function upsertDshServer(configEditor, { server, previous }) {
+  const config = encodeDshEntry(server);
+  if (!SERVER_NAME_RE.test(config.serverName)) {
+    return { ok: false, code: 'error.dsh.badServerName', error: `serverName must match [A-Za-z0-9_-]{1,32}, got ${config.serverName}` };
+  }
+  const rows = mcpEntries(configEditor);
+  const clash = rows.find((row) => row.entry && row.entry.id !== previous?.entry?.id && decodeDshEntry(row.entry, { ...row.inherited, ...row.override }).name === config.serverName);
+  if (clash) {
+    return { ok: false, code: 'error.dsh.duplicateName', error: `another MCP row already uses serverName ${config.serverName}` };
+  }
+  /*
+   * DSH identifies a server by serverName, so a coerced name is a different
+   * server than the one the user named. Report it instead of renaming quietly:
+   * a 32-char truncation can also collide with a row that already exists, and
+   * the user has to know before the row lands.
+   *
+   * One case is NOT a coercion and must stay silent: a name the harness cannot
+   * accept at all (CJK, spaces, punctuation elsewhere) is mapped by
+   * `dshMountName` on every path — write, scan, toggle, remove — so reporting
+   * that mapping as a rename would look like a bug on every CJK server. The
+   * test is whether the harness name is EXACTLY what plain sanitising produces:
+   *   - too long, ASCII      → sanitize alone truncates, so the characters were
+   *                            lost and the user has to hear about it
+   *   - CJK / punctuation    → sanitize alone would collide, so dshMountName
+   *                            appends a fingerprint and nothing was lost
+   */
+  const requested = String(server.serverName ?? server.name ?? '').trim();
+  const truncated = requested && sanitizeName(requested, '') === config.serverName;
+  const renamed = requested && requested !== config.serverName && truncated
+    ? { from: requested, to: config.serverName }
+    : undefined;
+  if (previous) {
+    try {
+      await configEditor.edit(previous.entry, (current, inherited) => ({ ...inherited, ...current, ...config }));
+    } catch (error) {
+      return { ok: false, code: 'error.dsh.write', error: String(error && error.message ? error.message : error) };
+    }
+    return { ok: true, entryId: previous.entry.id, serverName: config.serverName, ...(renamed ? { renamed } : {}) };
+  }
+  return { ok: false, code: 'error.dsh.insertUnsupported', error: 'adding a new MCP row requires the patch layer; see the generated snippet' };
+}
+
+/** Remove one MCP server row. */
+export async function removeDshServer(configEditor, row) {
+  if (!row) return { ok: false, code: 'error.dsh.missing', error: 'no MCP row to remove' };
+  try {
+    await configEditor.edit(row.entry, (current, inherited) => {
+      const next = { ...inherited, ...current };
+      delete next.serverName;
+      return next;
+    });
+  } catch (error) {
+    return { ok: false, code: 'error.dsh.write', error: String(error && error.message ? error.message : error) };
+  }
+  return { ok: true };
+}
+
+/**
+ * Mount or unmount one MCP row inside DSH.
+ *
+ * This is deliberately NOT a config write. mcp-client's schema has no
+ * `enabled` field, so "off" cannot be expressed as configuration; the Loader
+ * row's own `disabled` flag is the only real off switch, and `pluginManager`
+ * owns it. Using it means the process really disposes the plugin (its tools
+ * disappear) and really re-initialises it, and that nothing outside DSH is
+ * touched — no other client's config file is rewritten.
+ *
+ * `entryId` is the Loader row identity from `listPlugins`/`configuration()`.
+ * A server that only exists in the patch layer has no identity until the
+ * Loader reconciles it, so the caller has to report that instead of guessing.
+ */
+export async function setDshServerEnabled(pluginManager, entryId, enabled) {
+  if (!pluginManager || typeof pluginManager.setPluginEnabled !== 'function') {
+    return { ok: false, code: 'error.dsh.noManager', error: 'the plugin manager service is not available in this process' };
+  }
+  if (!entryId) {
+    return {
+      ok: false,
+      code: 'error.dsh.noEntry',
+      error: 'this server has no Loader row yet',
+      hint: 'it was written to the profile patch and the Loader has not reconciled it; reload the page to pick up the live row',
+    };
+  }
+  let result;
+  try {
+    result = await pluginManager.setPluginEnabled(entryId, enabled === true);
+  } catch (error) {
+    return { ok: false, code: 'error.dsh.toggle', error: String(error && error.message ? error.message : error) };
+  }
+  const application = result && result.application;
+  if (application === 'overridden') {
+    // A higher-priority composition layer decides this row; flipping it here
+    // would appear to succeed and then revert on the next reload.
+    return { ok: false, code: 'error.dsh.overridden', error: result.error?.diagnostic ?? 'a higher-priority layer overrides this row' };
+  }
+  if (application === 'failed' || application === 'cancelled') {
+    return {
+      ok: false,
+      code: 'error.dsh.toggle',
+      error: result.error?.diagnostic ?? `the plugin manager answered ${application}`,
+      managerCode: result.error?.code,
+    };
+  }
+  return {
+    ok: true,
+    entryId,
+    enabled: enabled === true,
+    enabledOnDisk: result?.enabled,
+    changed: result?.changed === true,
+    restartRequired: application === 'restart-required',
+    warnings: result?.warnings ?? [],
+  };
+}
+
+/** YAML snippet a user can paste to add a new row (we cannot insert rows). */
+export function dshSnippet(server) {
+  const config = encodeDshEntry(server);
+  const lines = [`- insert:`, `    - id: mcp-${config.serverName}`, `      name: '${MCP_CLIENT_PACKAGE}'`, `      config:`];
+  const walk = (object, depth) => {
+    for (const [key, value] of Object.entries(object)) {
+      const pad = ' '.repeat(depth);
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        lines.push(`${pad}${key}:`);
+        walk(value, depth + 2);
+      } else if (Array.isArray(value)) {
+        lines.push(`${pad}${key}:`);
+        for (const item of value) lines.push(`${pad}  - ${JSON.stringify(item)}`);
+      } else {
+        lines.push(`${pad}${key}: ${typeof value === 'string' ? JSON.stringify(value) : value}`);
+      }
+    }
+  };
+  walk(config, 8);
+  return `${lines.join('\n')}\n`;
+}